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• Write once, run on any platform 
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Because your new client needs to set project 
deadlines for a sales team in San Francisco, an 
IT group In Boston, and a CEO in Barcelona. 


Because the Internet is here to stay. 

Because deep inside, you've always toyed with 
the idea of becoming a superhero. 


4D Portal, the new, FREE Web application from 4D, inc., lets you 
develop customized applications that will change the way people work. 


Whether your clients need to solve workflow challenges, streamline 
communication processes, or brainstorm across time zones, 4D Portal will 
help you give them what they need, all within a Web browser. 


Don't you think it's time you saved the day? 


Download 4D Portal free-of-charge today at <'''':tp://ww/v.rTiy4DPortaI.co 
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nflAC os X 


By A ndreiv Stone 


What’s So Funny About Peace, 
Love and Mac OS X? 


One of my favorite riffs is why Apple is so freakin' 
groovy and it begins sornelhing like this: Once upon a rime 
there were two young men in their garage and they dropped 
some... Well, you know that part of the story - the light 
shined hrighi and I tlhnk George Harrison w^a.s playing. And 
as Patti Smith sings “This is an era where everycjne creates!*' 
And this has come to pass with the help of personal 
computers, with many of the innovaiit)ns coming from Apple 
(and NeXT). Tire rest of the indu.stry largely c:t>pie.s what 
Steve Jobs Co. do! Even the digital hui> concept is being 
ripped off by Intel - they had a full page ad in LISA Today 
the day after Steve inirodiued the new jMac. MacWorld Expo 
this year marked the transititjn init> OS X - all new ctJinpuiers 
are shipped with OS X as the default operating system. One 
of my favorite parts of the keynote was moment of musical 
iribuie" to the late great George Harrison, reminding us of 
our roots and gratefulnexSS to the visionaries tliat have come 
before us. Sales of the new iMacs have been phenomenal, 
and complementing this hardw^are renaissance, Ccx'oa is 
hound to create a software renaissance. 

Running a booth at Expo is both exlian.siing and 
exhilarating, bni is an essential nnmterpan to being a 
software hermit. Meeting your customers, giving demos that 
really excite people, and making impulse sales are all part of 
whai makes a show invaluable. Hut what really makes it all 
wnjrlhwhile is the occasional random, ghosl-in-Llie-machinc, 
basic Apple Magic encounters. On Thursday, a rather Tolkien 
lc>f>king fellow aml>les up to me and says fiey Andrew', 
here's an invitation to a parly we’re throwing!' He has an 
Apple employee badge, so I’m alt ears. He hands me a big 
linen enveltjpe. 'I'hinking of my comrades, I asked for, and 
received 5 more. “The Gay Idade and the Naked Mole Rats 
present..." - hmnim, definitely a little edgy, and it starts 
before the 'I he Rarty formerly Known As ... ('fhe Knife's l.ast 
Call), Running in to an old friend who was recently hired by 
A[)ple to promote unix ports, we fiave an imprompiu Thai 
dinner w'iih a bunch of t>ld NeXTSteppers, WehObjects guys, 


the original Darwin dude, and a guy from Sun who is looking 
for people to work on the OS X pon of Open Office 
Cwww.ijpenoffice.org). Only two guys join me for the parties^ 
hut we are rewarded might ily! 

We find the venue in a back-alley south of Market 
watering ht>le where ihcre’s an open bar w'ilh a decent 
microbrew, and a very fanujus band fat least in the rock and 
roll accordion world) takes stage, "fhose Darn Accordions' - 
<http://thosedarnaccordions.com/index.htrn> is a very original and 
liumorous l)and featuring 3 accordionists, and they lolally 
rocked the house. It turns out I had been invited to a very 
exclusive Mac insiders party: a veritable who's who in the old 
lime Mac community! During the set break, the band's lead 
singer, Eatil Rogers, turns the audience into the performers. 
He's a total Mac user, and he breaks out a long list of 
(juestlons of obscure problems lie’s had with his Mac, and he 
wants the audience to answer the questions. One by one, the 
world's Mac experts crack his questions, and it's a joy to 
watch our collective know'ledge in action. 

Finally, he comes to a tpieslkm - “Mac OS X is on my 
disk, and its taking up space. What .should I do - Nuke it? 
What's it good for?" 

]n the spirit of llie moment, I jump np on stage, grab the 
microphone, and ,say, “I can speak to that, fve been 
developing with Mac OS X's “new'” devefopmenl 
environment. Cocoa, hir 12 years. I shipped my first app in 
1989 on the NeXT, and followed the vision of object oriented 
software without lr>,sing faith, and now have 10 applications 
shipping for OS X. First - those problems that you've been 
having on your Mac - most of those (init conflicts, memory 
issues, crashe.s) would tritally disappear on OS X, Second, we 
are at the beginning of a renaissance - it w'as announced at 
Expo dial Apple would be sliipy;)ing the eniire Developer CD 
vAith every computer. Who knows wlicre tlic next killer a[)p 
will come from? 

Cfx'oa gives linkerers the ability to WTite fully integrated 
OS X software. To give you an idea of Cocoa’s power, you can 


Andrew Stone <anclrew@sione.com> is founder of Stone Design Corp <bttp;//www.,stone.com/> and divides his time between farming on the earth 
and in cyperspace. 
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Encore 



The new Mac OS X version of the award-winning project manager will soon make its debut 
on screens and in stores. To preview, pre-order, and find out more information on 
features and availability, call 800.346.9413 or visit 
www.fasttrackscheduleS.com 
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huild ^ word prcxressor tkit has multiple fonts, rulers, c'olors, 
ligatures, baseline, juslfic^ation, kerning, full undo, printing, 
spell-checking and even drag and drop of 30 graphic formats 
in just 8 lines of code! Putting the development environment 
into the hands of the users is extremely healthy for tlie 
biodiversity and future of OS X software." 

Anyway - the second set was even more rcx:king! 

Here's how to create a multi-document word pnx.essor that 
has support for graphics, colors, nilers, alignment, super and 
subscripting, baseline control, UNICODE, kerning, and it reads 
and writes RTF and K'l’Ff) files, 'llie 10 lines of code are for the 
reading and writing - the rest is provided via Interface Builder 

1. In Projea Builder, select “New Project,..", choose “Ctx^oa 
Dotument-lrased Application”, and save it 

<00„New_£'roject.tlff» 

Project Builder creates tlie main menu and document 
interfaces, and the MyDoatment subclass of NSDocument. 

2. Add the document types tliat wc can edit to the 
Application Settings pane of the 'larget Inspector: 

^Ol_Document_Types. tiff» 

Associate the Rich Text Format (RTF) and RTFD (with 
graphics) file types with “MyDocument”, 

5. Add the instance varialile text” to MyDocument subclass 
- only lK)lded text is what you write, tecause the rest of die tile 
was stublK*d out by Project Builder. 

// 

// Mynm-umciit h 

// XWord 

// 

// Cttattd by Andit^w Stone tm mfd Feb D6 2<)02, 

// Copyright fc) 200i _MyCompiinyfS’jmie_.Atl rights resen^d. 

// 

ilfimport <Cocoa/Cocoa.h> 

^interface HyDocument r KSDoeiiitent 

I 

id text; 

J 

Send 

4. Open MyDocumenr.ntb in InterfaceBuilder, drag 
My Document, h icon from Project Builder to add this instance 
variable to the File's owner (the MyDocument ck%.s). 

% Drag in a text view from the Cocoa-Data Palette window 
and resize tt to Oil window 

6. In die Size Info, dick the ‘"Springs" sproingy so that it 
grows to fill the window when you resize it 


7. In Attributes Info, click '"Undo Allowed" and Tiraphit^s 
Allowed" 

8. Control-drag from tlie File’s cjwner icon to the text view, 
and click on “text", and then Connect 


9. Open MiiinMenu.nib, and drag the Text and Font menus 
from the Cocoa Menus palette onto the main menu. Change 
cx:curren{:es of Newapplication to X Word. 


10. Fill out the read and write [primitives (the ujibolded part 
of this file was generated by Project Builder): 

// 

// MyDocuiBCtil.m 

// X Word : a 10 Ibe Graphic!* Enabled Word Proc^sor 
// 

// (by Andrew Stone on Wed Feb 06 

// Copyright (c) 2001 _MyCompianyNamc_.AU rtgln^ iiescrved. 

a 

^import “KyDocument.h" 
implementation KyDocumont 

- (NSStriog * J windowNlbNauie 
I 

// Override returaing ilic oib file natne iif the dcKumcnt 
// If you need U> use a subclass of NSWintlowfonttolkr or if your document 
iupports multiple NSWindowt'jontrollers, yon should remove this method and 
uvcnldc -maifeWindowCont rollers in.stead, 
return ^''MyDocumenL'*; 

1 

- (void)windowControllerOidLoadNibt(NSWlndowController *) 
aController 

( 

[super windoitfCotitrollerDidLoaiiNibtaCoEtroller]; 

//Add any code here that nt'cd to be executed once die windowCuntroller has 
loatkd the document 's window. 

\ 

^define Whole.Range NSMakeHangetO, [[text string] length]} 

“ iKSData *)dataRepresentatlonOfTypei(KSStrlng *)aType 
I 

If c taType isEqualToString:NSKTFDPboardType]) 
return [text RTFDFronRange:Whole.Range]: 
else if Ua^pe isEqualToString:KSRTFPboardType]) 
return [text RTFFromRange:Whole_Rangelj 
// add other types 
return nil: 

I 

(800LJloadDataRepresentation:(NSData U data 
ofType:(NSString *)aType 
t 

if (UType isEqualToStrlng: NSRTFDPbnardTypc]) 

[text replaceCha racte rs tnRa ngo:Who1G_Range 
withRTFBidata]; 

else if ([aType laEqualToStrlng:NSaTFPboardType]) 

[text replaceCharactersInRange:Whoie_Range 
wlthRTFidata]: 
return YES; 

) 

@end 


Save Lhc Oles, build it, test it, ship it! Ail you need is an icon. 
Or, you can grab the .source from: 

http./AAiww.stonexom/dev/X.Word/X.Word.lar.gz 
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WIBU-KEYBB the Other hand offers 
additionai benefits for your costomers on 
every platform Mac - PC - Unix; 


Dongles are out! 

m 


You are right. 

Simple Dongles are obsolete. 


WIBU-KEY is in! 


Software goes online 

Electronic Software Distribution - safely protected by WIBU-KEY 


Web Remote Programming 

Transferring data into the WIBU-BOX at the customer's site 


Web Authentication 

Authentication of the user with the help of his WIBU-BOX 


Pay-Per-Use 

Usage dependent accounting 


MacOS9&X 


WIBU-KEY supports Mac OS. Windows and heterogeneous networks i-800-986-6578 

Order Vour Test Kit 


iUIBU 

SYSTEMS 


WieO^SYSTEMS AG 
0-76137 Karlsruhe 
WIBU-SVSTEMS USA. tnc, 
Seattle, WA 93101 
email: info9wtbti.com 


G^IT 

hanmover 

13.-20. 3. 2DD2 
Hall 17 Booth €52 


, 9 griffin 

I liCHNOlOGlIfS 

USA, Canada: 6rifflHi Technalagies. LLC 
phone: (785) 832-2070 faa; (735) 312-3787 
email: s^le^^giiftech com vvww.grtftech.com 
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NETWORK 

MANAGEMENT 


By Joh n C. Welch 


USB 2.0 


A Comparison 


Wllcome 

With all the hype about USB 2.0, I thought it would Ik: a 
gcKKi idea lo aeUially lake a Icxik at its prottKol* its fundamental 
parts, and how it works. While USB 2.0 is not everything Us 
hackers insist that it is, (and noihmg is ever as g<xK.l as fans 
wi>u]d have us Ixrlieve), it is an improvement on the USB syxx, 
and a way for comj)anies to gel higher data rates without liaving 
ro sc^panitely develop for a different standard. 


USB 2.0 BACKCiKODNlS 

Hie original im|X‘tus for USB was the need for an easily 
configurable, expandable, fast interface. While the PC and the 
Mac both had many ways to attach devices, they all had 
drawbacks. Serial ports were slow, and difficult to configurx:; 
[larallel pons were limited as to how many devices they could 
use. PS/2 was a one-device-per-port standard, and it wasn^C 
dynamic; ADB was slow, etc. So Intek and later others, devlscKl 
Universal Serial Bus, or USB, USB is an auUMonfiguring serial 
bus that allows devices to connect at ditTerent speeds (1,5 and 
12Mbpsl without having to manually assign ids and without 
needing lerminaiion. It is able to tdislconnecl without fiaving lo 
sliut down the host device, A host device is required (although 
there Ls work Ix-'ing dtme to alleviate this in USB 2.0) so data 
transfers require host CPU inientipts, Tlie prof>tein with USli l.X 
was that after a while, IZMhps was loo .slow, esfX^cially for 
things like Cl) fiurners, digiuil camems, and hard drives. So, USB 
2.0 has added a third sjXed option, 4B()Mbps, 

USB 2.0 also adds support for reakime data transfers, 
important for video conferencang; support for isochronous 
transfers, im[XJrtam for devices that need m have giuirameed 
bandwidth, .such as video cameras; and support fur mixed mode, 
or simullaneous asynchronous and isoclironous transfers. 
Because of these new features, USB 2.0 nin alM) support more 
tievice types than USB l.X could. 

The Ixmefits for the end user have nt>t changed. You still 


have hot - swappal>le devices, an easy to attadi connector, 127 
devices per USB channel, automatic driver setup, etc. But as I 
s;ud, you get iscKrlironous transfers, which are critical for audio 
and video applications. Y(ju also get Ixiier support for different 
pac'kei sizes, error handling, and error recovery. 

Like any (ither bas .system, LISB has Ixith a physical and a 
logical topology that it hallows. With USB, the physical topology 
IS a tiered, t>r layered starfthink t>f a star overlaid on a pyramid 
with specific layers, and rhaUs the general layout.) Tliis topology 
is limited to seven tiers, with t:ertain tiers having limits as to the 
type of devices that am lie used ilicrc*. Within this her, there are 
two Ixtsic types of devices, fuibs and fuiKtions. Tier 1 is die host, 
and nK>t hub, and that is the only device at that level. Tier 7 can 
only have functional devices. You can have a comjxitmd device 
that is both a huh anti a function, but tluxse tjccufiy two tiers, 
with die hub one tier higher than the function. So, you cannot 
have coiiifiound devices at Tier 7. A liub provides attachment 
points to a USB bus, anci a function actually does something, 
such as a mouse*, or a hard drive. 

With USB, like SCSI, you have a single host tlxit controls all 
operations on the bus. Within USIL dus is called the host 
controller, and can be a combiitalion of liardware, software, 
and/or linnw^are. All host controllers liave a root hub, which 
provides one or more attachment poini.s, such as the USB ports 
on the back of your Mac. 

USB has Ixnh a physical siandartl for tlte interfaces on die 
system, and an electrical standard that provirles tlie signaling 
charac terLstic's for the bus. In general, USB utilizes a four-wire 
cabic, with two wires used for poinl-to-|X>int signaling. Tliree 
data rates are uscxl in USB: 

tllgh, or 480Mbps in USB 2 
Full, or 12Mbps 
U)w, or 1.5Mbps 

Note that with IKSH 2. you can transmit full and low5{X*ed 
data between the liost controller and the hub at the high speed 
rate, and then lK:iween the hub and the end device at either full 
(high?) or low speed, to minimize the impact of slower devices 


John Welch <jwck’fi«imii.e(ki> i.s die IT nianager Idr the MU' Police department. Me ha.s over tlheen years of exjxriena* at juuking computers work. 
He simialtzes in figuring out ways in wliich \o make the Mac ck> what noixxly l Links it can, showing lliai the Mac is the supcfior administrative 
l>laiJ’orm, and leaching others liow' to llsc it. 
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on faMter ones. Lowspeed support is Icx^ed dtjwn to a 
niiinl^er of ilevices, such as [iiioe, in order to avoid spt^ed 
degradiition on ihe I ms. In addittc3n to the two ckita lines on the 
bus. D- and [)+, the other two lines carry power, (Vbus) and the 
ground. (CiND). 

LISb 2 IS a polled bus, with the Host Controller initiating all 
data intnsfcrs. Ty[3ically, bus iraasaaions involve three packets, 
all initiated on a scliedule by the fltxsi Controller 'fhe first 
packet, or ‘token packet', describes tlic tyi>e and direction of the 
tmnsaerkm. ilie USB Device address, and the endpoint numlmr 
Data transfers from host to device, or from device to liast. This 
information is used by the selected USB device to make sure that 
it is gml>bing data that is irilended for it. I'he source of the data 
transfer then sends a data packet, or indicates that ii lias no data. 
Tile final packet is then a handshake packet indicating the 
.successful djia transmission, or lack thereof. In the case of bus 
transactions Imiween hubs and host cxintroliers, the transfers 
involve four packet-S. and are used to handle data transfers 
between the host controller and full or low sjxfed devices. 

All aiiaeliinerU.s on a USB bus occur through huBs. wliich 
use status bits to report the attachment, or removal of a device 
to the hast when the hub is polled. If die event is an attachment, 
then the htxsi enables die port, and addresses the USB devk’c via 
the control pifm at the default address, llie host then assigns the 
device a unique address, and deLcrmines if the device is a hub^ 
or a function. The host cremates its end of the control pipe using 
the a.ssigncd USB address, and an endpoint of 7ero. Ai this time, 
the USB device also provides the information to completely 
descrifie itself, such as ilie USB standard it is using, die class of 
the devitr, and die device vendor. If the attached devii:e wa.s a 
liub widi attached devices, then this happens once for each 
device on that hub. If the aliaclied device is a function, then the 
software for that function liandles attachment notific^aiitin.s, Thi.s 
i.s where you will get the notice that you need to go out and get 
a proper driver for your new USB doohickey. 

When a device is detached, tlie hub disables that port, and 
sends a removal indtc'ation to the host. This is handled on the 
host by the appropriate software. If the rctiioved device was a 
hub with atiached devices, dien the detachment for each of 
ihtxse devices must lie handled as well 

Tile USB 2 spec sets up four Irasic data transfer ty|x;s^ 

• Control: Used for device configuration, t:oniro!, and 

similar types of data, such as atiachmeni notifications 

• Bulk Data: For large^ bursty dam types, with great 

flexibility in how tlic data is transmitted. Scanners or printers 
are exanifiles of this kind of dam. Error coirection liap|xms 
in hardware, and the amount of data can vary widely. 

• Interrupt !>ata:For liincly, but reliable dam delivery, wlicrc 
human notice of the data Ls important, sue li a.H the cursor 
movements from your mouse. Tliis is a limited - latency 
transfer type, and the sfxcxJ Is determined by the rlevkx^ 
Explicit timing is not required, although if the data is 
interactive, that may pose time limiLations. 
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• l,st>cliri)noLLs Data: For data that needs a specific 

amount of rciicrved t>andwidtli, such as videoconferencing, 
'lliis data is continuous, and real-lime during all phases of 
data use, so timing related data is criliail and explicit, 
Latency Issues arc resolved via buffering at the end|xmits. 
This kind of data has less error cx)rre(tit^n, as things like 
Retries will have a detrimental effect on data liming. 

USB 0)MPONFNTS 

Host 

Tlic first pan of any USB system is the host, <^r ihe 
computer This is the centra I enrib^ for a LfSB implementation, 
and is invoh^ed with all as|>ecis of USB funcrionality, such as bos 
access and tlata flow. I'liere is only one host [jcr USB, and each 
host has tlircx.' major layers: 

1) USB Bus interface 

2) USB System 

3) Client 

The bus interface handles the electrical and pR>lcx:t)] layers, 
lliis b similar U> Ihe inlerface provided by I fSB devices. l>ut ihe Inis 
iniertace lias additional duiic^s imposed on the host of a USB 
system. 

The USB System uses the Uost (kintroller to manage data 
transft'rs between the ht>sl and USB devices. The actu:il interface 
lietween the LfSB System and the Host Contrtiller depends on 
ilie Host Controller hardware. The USB System works with the 
host < oritioller to perform translations between the LISB clients 
and the USB interconnect, including various USB features such 
as pfoUK'ol wrappt*rs. *I1ie USB System is also the layer tliat 
handles USB resource management* including bandwidth and 
bus [Vtwer. so liial dienes can acces^s the USB. llie USB Sy.stem 
is itself made up of three com]K3nents: 

1) Host Controller Driver 

2) USB Driver 

3) Host Softw^are 

The Uosc Controller Driver, or HCD, maps the various Host 
Controller implementations into the USB system, scj that a diem 
can comtiiunicale with its device, without having lo know' which 
Host Controller the device is connected to. 'fhe USli Driver, or 
USHD, provides the interface for dient to device 
cotiimunicalions. 'there is an inlerface lietween the HCD and dk: 
USBl), know' as die Host C',omroller Driver Interface, IICDl. This 
is defined by die o[x^rating .system the Host Controller is running 
under, an<l is not directly available to clients. 

'Ihe USBD also provides methods for data transfer, called 
I/O Keqtie.st Packets, (IRF), This are a re(|ues! to transport data 
across a specific USB pipe. In addition to lids, the USBD gives 
dienLs an afistraclion of USB devices for configuration and state 
management puqx>ses. To do thi.s, the USBD owas the default 
pipe, w'hich is the connection tliai all USB devictrs are acceswsed 
through h>r control needs, 'this pipe is a logical communication 
between the USBD and ihe USB device abstractum. If an 


oiieraiing system provides nt>nd]SB software for the loading and 
ccjnfigtiniiion of device drivers, then lliosc are usc:d by the 
drivers, insietid of the USBD interface. 

'Ihe Client layer is the cf>ntainer for the software that 
directly interact with the USB iiardware. This allows the USB 
.system software to manage the dient to device cnmmunication.s 
correctly, preventing the client from directly manipulating the 
hardware. 

Generally, the host, and host layers deal with the following 
USB functions: 

1) Attadiment and removal of USB devices 

2) Managing the Ilow of control data between tlie host and USB 
devices 

3) Managing the flow ol' non-control data lxtwi‘en the host and 
USB devices 

4) Status and activity siaii.stic collection 

5) Managing the electric;d interface Ixtween the Host Controller 
and the USB tlevices, including power management 

Ihere are twxj ways control information can be passed 
Ixawt'en a USB device and its liost: in-liand, or out-of-band. In- 
band means that the control infomiation is imermixed with ihe 
data, wliereas out-orband signaling ust‘s a separate pipe for 
control in forma I ion. Fvery l^SB device has a pipe that is used for 
USB siandard control llcw, called the delayli pi|>c. This pipe Is 
t>nly used for siandartl amtrol infonmiion. Iftlie device requires 
any device-unique in formal ton, then it c:tn use the default pipe 
for this as well. Tlie device can also create additional pipes for 
S|xcific eommtinioaiions that may not lx* a [Xiri of die standard 
USB .s|K*cineation. The USBD allows for the sharing of die 
di*fault pipe with its clients, and provides access to any other 
conlR)l pipes asstxiaied wiili a given device. 

As we stated earlier, there are four basic ways lo 
tninsfer data on a USB: Control, iHochronously, Interrupt, and 
fkilk. Rt*gardle.ss of the type, all data transfers are managed l^y 
the Host Controller, Hach device has an interface, or tnierfac’es, 
that allow a client to iximmuoicaie witli it, Imertaces are made 
Ilf) of pipes that handle the actual data Ihiw lxtwc*en the client 
and the device, via end[X)inis on the device. Tlie pipes and 
interfaces are created by ihe USBD at Ihe request of the Host 
.Software, w'hich also gives ihe Hosl Controller the needed 
service parameters for configuration requests. 

Pipes, which aa* used for all data transfers on a USB 
Itave a nuiiilxr of cliaracierisiic:s basi.tl on data rate, is the data 
steady or sfxmidic, how' king the data can lx- delayed prior to 
delivery, and if the kwt of the data Ixing tniasferred will lx* 
caiasirophic or not. We’ll go into more detail on pipes a bit later. 

Host Conirolicrs have to manage the various device 
slates lhat octtiir on a USB. 1'here are many possible stales that 
a UtSli device can tiave, some visible to the USB and the host, 
some are only vi.sihle to l!ie device. The visible slates are: 

I) Attached. Tlie mosi fKisir state, this determines if a device is 
phy.sically on the USB or not. Tliis state does not deal wnth 
any other states. 
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2) Powered. A USB device can obiain power either throuj^h the 
[JSB, (Bus ' powered), or via its own jx>wer supply, (Self- 
[jowered). One note here, even though a self-powered 
device can \ye plugged in and turned on, it is not considered 
to be in a Powered state until attached to the USB, and Vims 
is applied. A device can support multiple powered 
configurations, depending on the power source. Ihis allows 
devices to avoid c'anfigiirations wlien l)us powered that 
t:ould cause damage to tlie USB or tile liost. 

3) Default. Tliis state follows the powered state. Once power Is 
applied, then the device must wait for a reset from the bus 
bt^fore responding to any commands. After tile reset is 
received, then the device is usable. Post-re.sei, the device 
speed is determined. 'Hie device teniiination resistors 
determine if tlie device is low' or full speed is used. If die 
device i.s caf)able of high - s[ieed operation, then the decision 
as to whether it wdll operate at high speed is determined by 
the reset. If a high - speed device is operating in a full - 
speed envinmrneni, ihen it must reset correctly in that 
environment, and resjiond correctly to device and 
configuration requests, even if It cannot support all intended 
functionality ai full - sjmed. 

A) Address. Inanediately after the reset, tlie device is using a 
default address. Once the reset is complete, then the host 
assigns if £i tink|ue atklress, whic h is maintained if die device 
is suspended. Regardless of address, tile device res[>onds to 
any reciuests on its default pipe 

5) Configured. Once the addres.sing has Ix^en set, the device 
must bt! configured. The device receives a SetConrigiirationO 
rec^uest, ,and responds with a non - zen> value. 

6) Suspended, if the device has gone a specified pericxl without 
seeing any bus traffic, then it goes into the Suspended slate. 
In this .staled, all arldressing anrl configuration data is 
retained. In addition to this inactivity timeout, the device can 
also be suspended tf the port it is attached to is disabled. Any 
atiivity on the devite’s bus causes ii to exit the Susix.‘JKled 
slate. If die bust lias entered a suspended state, tlie ilevice 
can request the host to wakeup via the use of remote 
wakeiip signaling. This remote wakeup af>iliiy must be host 
txjnfigurable. 

Hie overall state of the Hosi Coni roller is linked to the 
states of both the rota hub and the t.lSB, as any changes in the 
Host Controller and/or the attached devices have to he reilected 
in such a manner that both components stay in consLsteni .states, 
as in w4ien a resume event occurs following a sysieiii waking uj) 
from sleep. 

Regardless of tlie function of the end device, all data 
across the USB is a serial iiil stream, that is (de)serialized by Lite 
Serial Inierl'ace Engine, (SIH) in the Host Controller. To manage 
the flow of data on the USB, the Host Controller genenites 
frames, (for full speed devices), and microframes, (for high speed 
devices). To create either, tlie Host Controller issues a Start Of 
Frame Token, or SOF. SOFs are issued on a regular liasis 
whenever the Host Controller is in a normal operating state, 


every 125psec for high speed devices and every 1msec for hill 
speed devices. ^OFs are generated regardless of bus activity, or 
lack thereof. If the Host Controller is alioiii to enter a p<iwer - 
reduced state, then it will stop generating SOFs. The SOF token 
holds the liighesi priority access to llie bus. To ensure that the 
bus is idle for SOF transmission, the USB hubs coniatn circuitry 
to isolate any active LransmiUers during the End Of (iriicm)Frame 
l>encxl. To track ilie current (micro)lfame, ilie host uses two 
separate methods h>r hill and high speed frames. Full speed 
frame numbers are at least eleven bits in length, and are 
incrcnicnted every itiisec, tlie rale of SOF transmission. The 
lower eleven bits of tlie frame numlier id included in each SOF. 
For high speed device.?, the microframe numbers are al least 
fnunecn bits, and incrcanenl every IZ^psec. Bits three through 
tliineen are included in each SOF' transmission, wliich means that 
tile same SOF packet value is transmitted for eight consecutive 
microframes before ihe SOF packet value increments. 

Regardless of speed, when a (micro )frame number is 
requested from the Host Controller, the numlx'-r used is the 
current mimher at the time tlic retiuest was fulfilled. Tlie 
(riiicTo)framc number returned by the host is a 32 - bit number 
whether the device is full or high speed. At the end of the 
(mitTo)frame, there is a quiet period, known as the End Of 
Frame, or EOF period. During liie EOF, tlie Host Controller 
ceases iransmis.sion, and any transmi.ssion.s scheduled for the 
(micro)fraine that just passed are retired. If the f-lost controller 
was executing a transaction whtMi the EOF starts, that 
transmission is Lcrminated. 

1'ranstnission eiTor handling is the host’s responsibility 
on a USB. While there are many types of transmis.sion errors on 
a USB, ihcy are all liantiled in the same manner. Each time an 
cmn occurs for a given transmission, an error count is kept, and 
the transmission is tried again. If tlie transmission is successful, 
the error count is reset to zero. If the eiTur count reaches three, 
then the transmission is retired by the host. In the case of high 
speed isochrontjus transfers, there is only one attempt at 
traasmitiing data, so no error count is kepi. 

ThtTe are also a numlier of software mechanisms that 
are used by the USB host components to allow it to interact 
efficiently with the L)SB devices. While ihere is no ix:al hard 
division of [alxor between the host and device interfaces, one 
retjuirement for the host is that it supports multiple Host 
Coniroiler implementations, as defined by the luxsi computer’s 
operating system. The purpose of the host and device interfaces 
IS to allow for different levels of abstraction, while allowing the 
system to operate together according to the USB .spec. 
'Fherefore, the HCD provides the abstractions for the Host 
Comroller, and iLs view of data transfers, and the UJ?BD provides 
the abstractions for the USB device(s), and their view of USB 
data transfers, llie overall USB system acts as facilitator for these 
two pans, and their data iransfers. Part of this includes things 
like buffer management anti data s|ieed synchronization. 

One thing to rememlier is that when you are talking 
about software mechanisms, is that they are very dependant on 
the operating system of the host cxMiiptiLen Linux, Windows, Mac 
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OS X* imd Mac OS 9 all have diftcTcficc?) in liow they ih things, 
and this extends to USB interactiuns. In any USB system, ini any 
operating sysLem, there are still basic tasks that need to lie 
fulfilled, DeiK'nding on llie ofierating system, the host hanclles 
these tasks, in otliers, the USB system handles tliem. For any 
i)[)crating system, the USB uhsL imes the existence of a 
s|^ecialized client, called a luib ilriver, that arts as a central 
'clearinghiiuse’ for the adilition and removal id devices from a 
particnlar hvih. When the hub driver receives notification ol 
these events, it uses the host software, other USIM) clients, and 
the oix'rating system to recognize and configure llu: devices. 

In the case of device attachment, the I tub driver is 
notified by ihtr physical hub that detects the change. 'Ihe hub 
driver uses this hub information to get a device driver from the 
USBl), which sets up the default pijK" lor the device, and returns 
a device identifier fo the hub driver. From here, there are three 
configurations iliai have to happen for the device to lx* ready for 
use. First, the Device Configuration. Tliis sets up ail the USB 
parameters for the device, and allocates all the USB host 
resources dmi arc' visit>le to the device. Hits is done by setting 
the configuration value for the device, A limited .set of 
configuration changes/alternate settings are allowed wiilunil 
having to reconfigure the device. Once this step is done, the 
device is ready, as far as it's concerned. 

rhe next step is the USB Configuration. 'I'liis is beouse 
in order to at luaJly create the IJSBD pipe that is ready for client 
use, additional irifomiation, not visible to the device has to be 
specified by the client. This is ini'onnaiion .such as the maximum 
amt Hint of data the client can traasfer per IRP, the maximum 
sendee interval for the client, the client notification ID, etc. 
'Uiese values are collectively known as die pipe's Policy, and are 
used to des^Tilx^ how the client uses the jxpe. 

Hte final step is the Funtlion Configuration, Once the 
first two steps are done, ilie pipe is ready for use, as far as the 
USB is concerned. This last step is used for any vendor or da.ss 
- S[)ecific setup the client may need to use the pipe. Hiis Is 
private data between the device and the client, and is not 
stambrtli/ed by the USBD, 

Tlie Host Controller Driver 

Hie MCI) itself is an abstraction of the Host Controller 
data and the Host Controller's view of USB data transmission. 
The iiCDI has the following rcx|uirements: 

It has to ]>rovide abstractions of Ixiih the Host 
Controller hiirdware, and the data transters by the Host 
Controller acro.s.s die USB, as well as an aKstraaion for the 
(de)a Ik Ration of Host Cl >ni roller resoutx'es to suppon 
guaranteed service to the IfSB devices. It also has to (tresenl the 
root hub and its fkrhEivior in accordance with the huh class 
definition. This means that the hub driver has to Ix^ able to 
interact w^ith the rexH hub in the same way as It would for any 
oilier hull. F.ven though the nxil huh can be imjilemenied in a 
combination of hardware and software, it has to lx* alile to 
respond to the device default address, it has to return tlescTiptor 
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infonnatitin, il Ixas to suppcjrt liaving its device address set etc., 
just like any other hub. 'Ilie only difference is, witli the rex jt hul>, 
since it is clfxsely integrated with the Ht>si CtmlrollLT, may not 
ret|uire lius transactions for these functions. "Hie IICD is the 
lowest tier in the USB software stack, and as such, has only f>ne 
client, the USBD, which maps recjuests fnmi many clients to the 
appropriate HCD, which may be managing many Host 
Controllers. Tlie I ICDl is not client accessible. 

llie USB Driver 

Tlie USBD is a collection of mechanisms that are used 
by operating system components, such as device drivers, to 
access USB devices. The USBD is the only access to a USB 
device, and USBD iinpleinentalions are all operating system - 
specific. A single instance of the USBD directs access to the 
HCDs that connect to the Host Coni roller, and from the client's 
point t>f view, the USBD tlnit the client connects to is managing 
all U>e USB devices attached to the USB. llie USBD presents two 
types of software mechanisms to clients: command ami pijK* 
mechanisms. The command mechanism allow clients to 
configure and control USBD operations and IfSB devices, by 
providing all access to the device's default pipe. The pi|>c 
mechanisms allow a USBD client to manage device - specific 
data and control transfers, but do not allow a client to directly 
address the device's default pipe, 

I'he specifics of USBD inirializntion art: dependent on 
the operating sysiern I icing used. When a USB is initialized, tlie 
managetneiil inlbnnation for that USB is also created, and 
contains the default address device, and the defatih pipe used to 
communtaiie with a newly reset device. Wlien a device is 
alliiched to the USB, it responds to a default address until the LlSti 
can as.sign it a unique address, and it's default pipe* is made 
available to the hub clriver. flits (Kxiirs during device initializiiiioru 

Tile default pipes are managed by the USBD, and 
never accessed directly by tiienLs, although they am !x* tested to 
help fulfill client requests by various command mechanisms. 
Examples of default pit^" data transfers are things like seltitig a 
device address. The USBD is directly responsible for allocation 
and managing appropriate buffering for these transfers. All other 
pipes are client pips and are managed by the USBD clients. All 
iiuffering and oilier management of client pipes are handled by 
the client. There are four tyfxs of diem pipes, to handle the four 
types of tiata transfers we spoke aboui earlier, namely 
Isochronous, Inlemipt, Bulk, and Control. Along with these lour 
pi|X‘ types, there are three basic pipe mechanisms: AUnt, for 
pipe abortion, Pipe Policy Management, and Queuing. These 
mechanisms in turn .support ceruiin basic cxipabililies, such as 
Configuration Services, Configuration Management, Initial 
Device Configuration, Device Configuration ModifiealUm 
Management, Device Removal, Power Control, IZvent 
Notifieation, Status Reporting, Error Recovery, and Remote 
Wakeup Device Management. 

finally, there are systems, Macs among them, that 
implement USB services l>efore the operating system loads. ‘Ibis 
is so you can use Open Firmware with a USB keyboard. In these 


cases, as the operating system l<.>ads, the Host Controller 
provides a mechanism that disables this prebooi access, and 
allows the opemting system to gain control. Onc:e the operating 
.system gains control, it is respoasible for fully configuring the 
USB. If the opcTating system has to pass control of the USB back 
to the preboot system, then the prebcxii system should treat tliis 
as a power up event. 

USB Devices 

‘the next USB com|>oneni to l(H>k at are the devices 
themselves. Each device has three basic pans: 'ilie bus interface 
tliat handles packet I/O, the jniddle layer that routes ckita between 
the bus mterthce and the device endpoints, and the tof) layer Uiat 
is the device fiinaionality, such as a mouse or keylxjard. 

When a device is attadied, or dettched from a USB, the 
liusi uses bus enumemtion to lutndle these changes. Ftjr example, 
when a device is attac'hed to a powercxl port, you get diese actions: 

1) Tlie hub with llie new device tells the host via the siatiis 
change pipe. At this point, llte device is P<nvered, but the 
port it is attached U) is disabled. 

2) The liosl queries the hub to determine the precise nature f>f 
the change. 

31 Now the that the host ha.s the fxjrl for the new device, it 
wails for at least 100msec to allow the in.senion to complete, 
and the power at the device \o lx* stable. The host then 
issues a port enable <x)mmand. Iblk)wed by a reset command 
to thai port. 

1) Ihe Imb f:)erfonns the actual port reset. Once this reset signal 
is releasetl, the port is enabled. The USB device is in the 
Default Slate, and can draw' nt) greater than iOOniA from 
Vl>ys. All of the device's registers and .states have l>een reset, 
ant! it answers on die default adclress. 

5) The ho.st assign.s a tmkitie address to die device, and the 
device moves to the Address stale. 

6 ) The host then reads the device descripttir 10 deiermine what 
the raaximum data payload dial the device's default pipe can 
handle is, then assigns the device a uniejue address. 

7 ) The host reads the configuration information for all of llie 
device’s configu ra i i o n s. 

8 ) Based on Uiis information, and the purpose of the device, the 
host assigns a configuration value to the device, Tlie device 
is now in the Configured state, and all the endpt)ims for this 
configuration are set. The device can now' draw needed 
power rrom Vlnis, and is really for use. 

When a device i,s detached, the lK)si is notified by the 
hub. Tlie htxsi dien dis;ibles the jxm the device had been 
attached to, updates its topological information, and releases ihe 
device’s address. 

To support the dynamic enviromiieni of the USB, a 
device can Ixegin inteiacting with the USB almost as sfx>n as it 
has returned an ACK following its initial sciup, and tliere are 
various time limits to fat:ilitate the different stages of device 
setup. Following a reset, die device has a JOmsec interval before 
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it is <jx(Tcxtecl to sUtrt processing requests. I'his is CDnsidered n 
recovery f>em)d, ato applicable to resuming opemikm following 
a SLisf>end. After a recovery inlervaft of the device receives a 
request to .set its address, it has to he able to complete this 
rec|Liesl within SOnisec. Once the device has pr(K:es.sed the set 
address command, it .sends an acknowledgement l>ack to the 
LISB indicating that die device address was successflilly set. At 
this f)(jint, there is another recovery interval of 2m.sec, following 
whicli the device must l>e able to resprintl to Setup packets sent 
to rlie new addres,s. 

If the device handles device requests that need a data 
stage transfer to the host, then the device must be aide to return 
the first cLua packet to the host within SOOmsec of the first 
request. All subset|ueni packets must l^e returned within 
StK)insec of the successful tnmsmisston of the previous packet. 
After returning the final data packet, the device must finish the 
status stage within ‘SOtnsec of returning the final data packet. 

If the device is handling device requests ihai need a 
data stage transfer to the device, then the USB has an up[X-T limit 
of 5 stxonds to prtxx'ss a command, although this is no\ a liard 
limh, and can change depending on need. 

Since a high - speed device fuLs to lx;‘ able to operate at 
lx)th high ' and full • speeds, it has to lx: set ft)r the speed of the 
liSR, dejx-'nding on bus .s|x^ed limits, Tlits is nornialiy done as part 
of the reset processing. Once the devkx specxl his l>eeo set, it 
dtx;sn I change until the next lime it is reset, f'he high - si>eed 
device must reporl to the IfSli any limitations in its ftinctionalit)^ 
ihai may exist lor a given S|>eed. It does this during a>nfigumtion 
by returning descriptors for its current openning sfxxd. If ncxd 
Ixf, the USB can get descriplors for liolli itKxles, and set the device 
to llic USB's limilalion, t>r device use on that USB. 

All USB devices respond to host rcx]uests on their dc!fauli 
pipe via control tnmsfers sent in a Setup packet, wliich is eiglit 
bytes in length. Radi Setup packed has five fields that define the 
ixxiuest, and its panimeters. 11ie first field Ls hmRei|yes!Typt% and 
identifies the sjX'cific rcxpiesl parameters, such as direction of data 
tnmsfer, the lype* of transfer, and the Rxtpient of the transfer. 
bmRcxjuestType i,s one byte long ITie next fiekl, hHcx|Ucsi 
sjxcifies the particular rec|ues1, is one byte long, and is modified 
by the lype infonnaiion in bmKct|uestTy[>e. wValue, the third 
field, is I wo bytes long, and is used to pass a re( |uesi - specific 
parameter to the device. 1he next tVkI, wlnclex, is similar in 
hmdion to wValue, and is also iwti bytes long. The final field, 
wLcaigih, is alM> two byles long, and shows the lengili of ihe cUla 
iluit will Ik^ tninsfened during the second phase of the control 
transfer. Note that the cLita transferred may have a lengili that is 
less than wlcmgih, but never gieaier. 

As we saw earlier, USB devices respond to 
configuration infonuiition reejuests via descriptors, A descriptor 
is simply a way of storing device c^apabiliiy dc'scriptitms in an 
easy lo • retrieve manner, that can reuse parts of other 
configuration descriptions for that device, much like a database 
record can use similar informal ion that may lx: conuiined in 
oilier records or fields. Each descrifnor starts with a one byte 


field tlial contains tlie total numlier of bytes in the destrriplor, 
followed by a one byte descriptor identifier. If appropriate, the 
descriptor tun contain Inmian - readable infonnation in the form 
of strings. If the descri[>lor leiigtli value is less than the 
sjxxificalion - defined length for that destriptor, then it is 
rejected by rlie host. Tf the descriptor is laiger than the defined 
length, then the extra tlata is ignored. 

Tf the descriptors are class or ventlor ■ specific, tiien 
there are two ways for the device to deal with them. If thy 
use the standard descriptor formal, then they are returned as 
a standard descriptor would be returned, and can be 
interleaved whth standard descriptors. If they modify a 
standard descriptor, then they must ftdlow that descriptor. If 
ihey use a non-standard formal, then the descriptor recjuesi 
specifies the class/vendor - sptxafic descriptor and index, to 
retrieve that descriptor from the device. 

There are seven standuixJ device descriptors, whicrh can 
only lx imxlified by nitxlifying ihe USB specifiralion, and am: 

1) Device. This descriptor gives general, global, non- 
configLiraiion - specific infomiation aixjut the devic:e. If the 
device is a high - sfxed device, anti lias different information 
for high and full - speed o|x:raLit>ns, it must also have a 
device_qualificT descriptor. If tlie device is capable of high 
speed t)peration, then it returns a 2.0 as its version riumlxr. 
If the device is a full or kiw speed only device, then it 
remrns an error Lo a ret[uesl for ihe device_qualifier 
descri[)l<m 

2) Device_qualifier. Iliis descripior contains the information 
alx>ut a high ^ spt:ed tlevice dial will cliange if the device is 
operating al a dilTereni sjxed, 

3) Configuraiion. 1'he configuration tlescriptor contains a 
specific configunition s informaikm. So if a liSB camera has 
tlifferem operational cliaracteristics depending on the 
camera's senings, each of ihese gets its own ctmfiguraiion 
descriptor. 

4) Interfatx:. 'Iliis tlestribc-s a specific interlace within a given 
configunition, and a given configumlion can have multiple 
interfaces, each with its own deseri[iior The interface 
descTipior Ls always relumed as part of a configuration 
descTi[7tor, and cannot be accessed separately. 

Endpoint. This descriptor is for each endfxyinl within a given 
interface. Like ilie interface descrifHor, ti is returned as part 
of the configuration descriptor, and cannot be accessed 
separately. 

6 ) String, itiese de.sc’riptors are oyaional, and are UNICODE 
strings. They are used if there is a need for human - readable 
desiripiors. 

USB Hubs 

The third physical componenl of the USB spec Ls the hub. 
USB hubs are a critical part of ilie VSB, and do much of the 
work involved in making USB as easy to use a.s it is. Hubs mtist 
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deal with connection tehavior, power management, device 
(dis)c()nne<iion management, fauli delecLion and recover, and 
support for liigli/lull/low - speed devices. Hul^s in a high - 
sj>eed environment must also isolate the high - speed signaling 
from the full/low - speed signaling to ensure thai liolli 
interofx.Tale correctly. 

Tliere are three basic components to the USB hub. llie first 
is the Hub Repeater, which manages connectivity lietween same 
- speed upstream and downstream pcrrLs. The repealer also 
handles the Iiub entering and leaving tlie suspend state, 
including remote wakeups. Ihe next component is the Hub 
Controller which manages host acce^ss to the Iml) along with 
providing status and control. Finally the Transaction Translator 
handles split transactions, (Split traasactions are, for example, a 
full - or low - speed transaction on a high speed hub that has 
low or full speed devices attached.) The speed of a device on a 
downstream port determines wliether the port is connected to 
tJie Hub Repeater, or the 'I'ransaction Translator. 

If the upstream port on the hub is attached to a full or low 
speed environment, any high - speed functionality is disabled. 
This also disables the transaction translator, and aD fXJrt.s are 
connected to the hub repeater. If the upstream poti is atladied 
to a high - speed environment, then the full/low - syreed repeater 
is disabled, and the huh repealer is a liigli - speed repeater. If a 
full/low ^ .speed device is attached, then the p<m must conntxi 
to the transaction translator 
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For data traveling upstream, the conncx:iion is a line, in diat 
one downstream port connects to the upstream port of the hub. 
If there are many hubs in line to the host, then each huh only 
connects a single downstream to iip.stream port. If the data is 
llowing downslreaiTi, tlicn the transmission is more of a 
broadcast, whereby all active downstream ports on that huh get 
the data from the upstream port, regardless of what device the 
data is uctually intended for. If the device isn’t supfxrsec! to get 
tlie packet, then it discards the packet. 

USB Bus Elcctro/Mechaiiical Characteristics* 

I’he next thing to look at is the actual USB physical bus 
characteristics. USB 2's different operating modes have 
different mechanical and electrical requirements, and there is 
a nt)ininal dividing line, with low speed, (1.5Mbps) on one 
side, and Iligh/Full speed, (480/12Mbps) on the other For 
example, High and Full speed both require a shielded cable 
with twisted pair wiring , whereas that cable is only 
recommended for low speed operation, 

USB uses a keyed connector protocol, both for ease of use, 
and to minimize termination i.ssues. There are two types of 
connectors, Scries “A" and Series “B”, Series “A" connectors are 
the familiar flat connectors that you see on the back of modern 
Macs, and are used for upstream, (towards tlie host system or 
huh), conncciions. Scries "B" connectors arc the smaller, square 
- looking connectors and are normally only used for 
downstream, (towards the device) connections. In any case, a 
,St?ries connector can only attach to a Series ‘'A” receptacle, 
and the same holds ime for Series “B”. (you may be asking 
about devices that have a Series “A’’ receptacle requiring a cable 
with two Series “A’' connectors, kemember that a device can also 
be a hub, and that hub connectors arc Series '‘A’' connectors. So 
tilings like keylxiards that can be hubs and devices use Series 
“A” connectors, whereas a printer that is only a device would 
use the Series t:c>nnec:ton>.) 

USB cable consists of four conductors. Two are used for 
power. Vijus and GND, the other two are used for data, D+ and 
Dv Within the enable, the conductors are colcir ccxled as follows; 
RethVBUS , Black=GND, Green=D+, White^D-. Tlie pinout of 
USB connectors is standardi7.ed as well: ]=Vitus , 2=0-, i=D+, 
4=GND, and the cable shell acts as a shield and drain wire. 
There are three lyfies of cables in the USB sj>ec, standard 
detachable cable, high/full - speed captive cable, and low - 
speed captive cable, (in plain English, a captive cable is 
hardwired to ihc device, ala an Ap[)lc kcylioard.) 

Standard detachable cable lias a Series “A” connector on the 
hub end and a Series "B” connector on the device end. These 
cables should only l>e used for fiigh/full - speed devices, as they 
can exceed tlie lengtji limitations for low sjm^d devices. This 
cable must also meet inipedance, signal pair propagation and 
delay requirements for high/fiill - speed devices. The GND 
conductor doesn’t actually earth tlie device or liub, Imt provides 
a common ground reference between the up and dowastream 
ports. 'Ihe maximum cable length Is limited by the. voltage dn>p 
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acn>ss tlie GND tonducttjr. 

Iligh/fiill - speL^cl captivcf cable is identical to standard 
detachable cable, except that one end is hardwired U> the 
device, and tliat it can Ik^ used with low - speed devices as well 
as higli/full - sj>eed devices. If it is used with a low' speeti device, 
tiien the cable must meet all tow - speed recjuiremenis. 

Low - speed captive cable is identic'a! in design to higli/full 
- sfxfed captive cable, but may only l>e used with low - speed 
devices. Any other cable designs are prohibited by the USB spec. 

USB Electrical Characteristics 

In addition to the bus electrical chanicieristics we just 
lcK)ked at, there are quite a few oiher elecinaji cliaraclerisiics in 
USB, sLieli as power distribuLion, signaling, and physical layer 
specifications. With the addition of high - speed mode in USB 2, 
there are some additional requiremenis that affect the electrical 
characteristics of USB. Things like the re{|uireinent tliat all USB 
2 - compliant hubs supfxjit high - speed mode, any downstream 
tonsceiver must support all three miKles, and that the c^abling 
used stipport all if tree mtjdcs are examples of tills. 

The new 480Mbi)S data rates in USB 2 require new signaling 
and termination characteristics to enable reliable operation at 
these speeds. High speed cable is terminated on botli ends with 
a resistance from each wire to ground. This resistance is set to 
one - half the overall differential impedance of the cable^ which 
is 45 ohms, for a total differential termination of 90 ohms 

When initiating a high - speed iransmifision, the transceiver 
starts an internal current source, derived from the ixisitive 
supply voltage for tlie transcreiver, and sends that current d<iwn 
either D-r or D- via a htgli - sptxxl current switch. If the current 
is sent down the D+ line, then a J state is being signaled, and if 
the D- line is used, then a K state is signaled. Data enccxling 
follows an NZkl .sc^hemefNZRI is an encoding scheme wlicre 
each lime a 'o' Is sent, the value of tlie signal changes from low 
to high, and vice-versa. USB 2 uses NZRI with bit stuffing, w^hich 
adds a ‘0’ after any six consecutive 'T.s, io force a tninsitions, and 
aid with cl<Kk .synchronization.) The actual voltage levels are 
detennined by the magnitude of the current source, and the 
value of the termination resistors As stated tKLTore, tlie resistance 
from cither f>+ or D- to ground is 45 olims, and the output 
voltage differential between lines is plus or minus 400mV at tliat 
resistance. 1he differential voltage is used to detect things like a 
had connection, or that tlie device has Ijcen disconnected. 

As far as actual signal levels go, in general, the difference 
between a T’ and a 'O' Is 200mV for differential systems. When 
in a J suite, low speed connettions are signaling a differential I, 
and full speed connectioas are signaling a differential 0, For the 
K state, these are reversed. 

In low/full - speed systems, the SOP is signaled at the 
origination port hy driving lK>Lh D+ and D- from the idle state to 
tile K state. To signal the End of Packet, HOP, D+ and D- are 
driven to a J state, then to the Idle state, and the bus termination 
hold the l>us in tliat state. In a high .speed connection, the Idle 
state iS when ixjth D+ and D- are nominally at GND, I'he SOP 


is signaled by driving Ixnh data lines into a K state. The HOP and 
idle slate are achieved by simply halting current flow into the 
data lines, and returning them to GND. 

Another fundion of the USB electrical system Is tliat of 
ptiwer distribution. As wit h ADB, and PS/2 even, the bus 
supplies [X)wer for devices to operate. Unlike the other tw^o 
though, you cm also have a self-p^iwered devic^e that doesn't 
need bus power, an iniportam consideration w4ien you are 
trying to hook up over a Itundred devices on a ,single bus. 
Finally, there are also facilities to warn that a device needs loo 
much power, and disable that dcvicir, witfioui shutting down tlic 
whole bus, or worse yet, burning out any components. 

To lacilitate easier operation of the power distribution 
system, USB introduces tlie concepi of a tinti load. A unit load 
i.s a 100mA load on the bus. A device dial only draws lOUniA is 
said to use one unit load, and is a low power device, A device 
can draw^ up to 5(K}mA, or five unit loads, anti is fhen considered 
a high power device. All devices default Ur low-]x>wer, but can 
transition to high jx>wer althougli that is under software control. 
The software has to make sure that going to high power will not 
damage the bus, before allowing that transition to lia[>pen. 
thereby avoiding some of the problems that an overloaded ADB 
Ixis could cause. 

There are a number of Ixiih power source, and jxiwer 
consumption devices, including: 
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• Rcx>t port hubs- Vhese amich directly to the IMl Host 
Controller, and derive power from the same source as the 
host controller. If the liuh is ]:x)wcred via AC or DC external 
power* then it must supply ai least five unit loads to each 
port, ft the huh is battery powered, then it can supply either 
one or five unit loads. A five unit load port is a high power 
pon, and a one unit load port is a low power port. 

• Rus - poweretl hubs. ITiese draw all power from Vbus on the 
hub's upsireani pt>rt. They can only draw^ up to one unit load 
on power up, and up to five following configuration. This is 
spill amongst the huh* its port.s, and any other hub functions. 
The ports on this hub are low power ports, and must 
maintain that current when the hub is in the Active, or the 
Suspend states, dliis type of hub can have five ports, one 
upstream, and four downstream. If more downstream ports 
are required, then the hull nuisi he self-f>owercd. 

• Self ' powered hubs. Tliese do not use Vbus as a power 
source. This hub may draw' a unit load from Vbus to keep 
the interface working if the rest of the huh is pow'ered down. 
As with the root porl hubs, if a self - powered hub is 
supplied by external AC or DC p<jwer, then all ]:>orts must 
high pow'er ports, if the hub is battery powered, then the 
|X>tts may lx* high or low power polls. 

• Low - power bu,s functions. All power conies from Vbus, and 
tfiey can draw no more than one unit load. 

• Higli “ power functions. Uses Vbus ns its power source. 
Draws up to one unit load on power up, and up to five unit 


loads following configuration. 

* Self - powered ftmetion. No operating power froiii Vbus, Irui 
may use one unit load from Vbus to keep the interface 
wtxking when the function is powered down. 

To avoid problems in wrong - way power distribution, no 
device supplies power to Vbus on the upstream feeing port, 


USB Bus Protocol 

Like any other networking protocol, ILSB has a protocol 
layer that defines packet layout, media access, etc, USB is a 
little-endian protocol, in that it sends data across the line 
starling with the least significant bit, and ending with the 
mo.st significant bit, (Considering tliat tJSB was started l)y 
Intel, the large.st supplier of little-endian CPUs, this is not 
surprising,) Byte - ordering is more important to lower layer 
functions lhan user - level af)plic:aiions, as ihe upper layers 
of the OSl model handle byte - order issues. 

All packets begin with a SYNC field that is used to align the 
data with the local clock. 11ic size of fire SYNC field depends on 
the speed of the USB, with 8 bits being used for lowvfull speed 
anti 32 bits used for high speed. 11ii.s field is only used for 
synchronization. The last two bits of the field are used to identtiy 
the end of ilie SYNC field. The Start of Packet delimiter is also 
pan of the .SYNC field. 
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Immediately after the SYNC field is the Packet Identifier 
Pield^ or Pll>. I'he PLD is made up of a four - l>ii packet type, 
and a four - bit check field, 'rhe type field indicates tlie tyfjc and 
R)rinat t>(‘ the packet, and the check field assists in tiie relial^ility 
of decoding the packet. Eacli i)iL in the check field is a 
complement of ifs respective bit in the type field. 

Addressing is done via two fields, function address and 
endpoint. Functions must always decode both fields, and a 
mismatch on either causes the packet to lx; ignored. Aliasing of 
cither field is not permined. The fiinaion address field specifies 
either the source or the destination of the data packet. ’Hie 
endpoint field is used wlien more than one endprjint per 
function is recpiired. 

The frame number field is eleven bits in size, and is 
incremented by the host on a per - frame basis. T'he 
maximum frame number is 7FFIi, and the counter rolls over 
upon hitting this. 

Tlie data field can be anywlicre frcjm zero to 1024 bytes in 
size. Data within each byte is shifted out LSB first. 

USB 2.0 uses tw*o CkC checks^ one for the token, and a 
second seirarate one for die data liits. The token CkC is five bits, 
the data CRC is sixteen bits. Tlie token CRC d<x*s not cover the 
Pli), which has its own check field. 


USB Data Flow 

Our final section deals witii the data How within USB 2.0 
Tills is where all the various sections of the bus work together 



Professkmal Software Developers 


Looking for career opportunities? 
Check out our website! 

Nationwide Service 
Employment Assistance 
Resume Help 
Marketability Assessment 
Never a fee 

Scientific Placement, Inc. 

800-231 -5920 800-757-90()3 (Fax) 

das @ scientific .com 

___ J 


to get your device to operate cleanly with your Mite, PC, 
whatever. 

The first aspect we have to look at here is the endpoint. The 
formal definiLion of a USB endpoint is that it is “a uniquely 
identifiable jxjrtion of a USB device dial is the terminus of a 
c'ommunication flow' between die host and device,” Remember 
that each USB device am have multiple endpoints, all grouped 
together in a logioil device. This logic'al device is what is given 
an address by the USB when it is attached and configured. 
Within the kigical device, each endpoint has it's own unique 
identifier dial is determined l)y the device. Bach endpoint also 
has its direction of data flow determined by the device. The 
c:ombination of logical device numl>er, endiioint numl)er, and 
directional flow ensures that every endpoint is able to lx; 
uniquely referenced, (Tills is logical, ics you wouldn’t want data 
for your USB printer sent to your keylxiard.) Beeau.se all 
cndfXTinus are simplex, the direction of data flow is able to be 
used to help reference that endpoint. (More simply put: 
Kndpoints are eidier goziiitULS or gozouta.s, noi both,) 

In addition to the other identifiers, the endpoint ha.s otlier 
chamcteristics drat ficlp destTibe it and its capabilities, such as 
bus access frequency ret|uircmenLs, bandwidth requirements^ 
error handling requirements, maximum packets size, and 
iraasfer types. All endpoints other than endpoint zero are in an 
unknown state until after device configuration, and cannot be 
handled until configuration ha[)f3ens. 

Fndp<.)int zero is used to impieinent a dclault control 
metluxl to and from the device. 'Ibe USB system software uses 
endpoint zero to initialize and manipulate the device as the 
default control pipe, whicli supplies access to the device 
configuntiion information, and allows for generic status and 
control acccs.s. Tlie default control pipe supports control 
transfers, and is available once the device is attached, powered, 
and Itas received a bus reset. 

Functions can have additional endpoints as needed, limited 
l->y the device s}>ecd. Low speed functions can only have two 
additional endpoints, whereas full speed endfx>inLs can have an 
additional 30 endpoints, (15 input, 15 output.) These endpoints 
are unavailable until tlie device has finished configuration, 

1'he next structure is the Pipe, wlitcli is the association 
between the endpoint on a device, and the host software. 
Pipes are how data moves between memoiy buffers on the 
liost, and the device endpoints. There are two types of pipe 
communications, each mutually exclusive: Stream, or 
unstructured data flow through the pipe, and Message, or 
structured data flow tlirough the pipe. Regardless of suucrure, 
or lack thereof, the UJiB doesn’t interpret the data moving 
through the pipe(s). 

In addition to data sinKlure, pipes have some other 
characteristics, such as btis access and handwidtfi usage, transfer 
types, and the characteristics of tlie endfxnnt llic pipe is 
connected to. If the pipe is conneaing two endpoint numbers 
zero, then it is know'n as the Default Control Pipe. Tbis pipe is 
available after the bus reset, but prior to configuration, whereas 
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other pipes are iinavailablc unlit after coiillguration. lliis ts 
because itie defauk coniro! [>tpe is used to configure the device, 
and tu detennine the device identification. Once I his is done, 
then tile default control pipe can be used by the device specific 
software. Ht)wever, ilie USli syscern software owns the default 
control pii>c„ and mediates its usage by other clteni software. 

As we said l>efore, there are Ixith stream and message j>if)cs 
in a LiSB, Siream pipes deliver unstructured data lietween 
endpotnis. Data hows in one end and out of the ocher, ancl 
stream j>ipes are always unidirectional. Stream pipes interact 
with what the USB sees as a single client. If multiple clients are 
using a single .stream pipe, Uicii no synchronizalion is provided 
for diose clients by the USB. Data ftow in a stream pipe is 
sequential, in a FIFO method. Since siream pi(>es are 
imidirectional, they arc lK>und to a single end|x>int that is 
I Kindling data in llie appropriate direction. Stream pipes suppon 
bulk, Isochronous, and inreraipt transfer type.s, 

As we said before, me.ssagc pif)cs pass structured data. 
There is also a different tnctliod towards how the data is 
Lransferred. Instead of just jamming data down ihe f)i[)e, a 
request is sent to the device fnini the ht^sl. Tlien die data transfer 
happens in the appropriate direction, followed l:>y a status stage. 
This data flow procedure is the reason for the structuring of the 
data in the pipe, so that the diffcTcnt daia types can Ik* 
identified. Me.ssage piptfs c:an Ik bidirectional, and the default 
control pifie is always a message pipe. 

Since the device is only required to service a .single mes.sage 
request at a time per tTiess;ige pipe, the USB system software 
enstires ifiat multiple concurrent requests are not sent to the 
(>ipe. Multiple software clients on the host can make ret|iiesLs via 
the defauk control pipe, but they are sent lo die device on a first 
‘ come, first served basis. l>aLa flow during the data and status 
stages is dciemiincd by the device. A message pipe to a devi<'e 
request a single device endpoint numl?er in both directions, and 
are used for the control transfer type* 

We have previously slated that there are four data ininsfer 
types in a USB: Control, Isochronous, Inrermpi, and Bulk. Lefs 
take a look at these in more dtaail. 

Control transfers allow access to different parts of a device, 
Tliey are designed to support configuration - type command.s, 
such as configuration and status types of communication 
between diem software and die function it needs to access. 
These eommunications, done via message pipes, again, use the 
three part request/data/status m<xlel for data flow. 

All USB devices have at least one control pit>e, the default 
control pipe, liui can liave more if need be. Ihe packets that 
travel via control transfers have four poasihle depending 
on the speed of the transfer: 8 bytes for low - speed transfers, 8, 
16, 32, or 64 liytes for full - speed traasfers, and 64 l:>ytes for high 
- .speed transfers. This size applies to the payloads of data 
packets, and is signaled by the endpoint via the device 
descriptor. Status packcLs are always 8 bytes. 

Although control transfers can run as fast as the USB 
will let them, there is no way to guarantee a specific speed 


for a control transfer. Although the USB requires that part of 
each {micro)frame be available for control transfer usage, 
they are not allowed to take needed liandwidtli from data 
tran.sfers. If need be, the USB syslcm software can also after 
the speed of control IransftTs. As well, the total number of 
control transfer bandwidth usage is limited, to avoid control 
transfers .stealing too much liandwidth. 

Tlie next transfer type in USB 2,0 is Isochronous, familiar 
to Mac users via FireWire. In USB 2.0, a re(|uc.si for an 
iscKhronous tninsfers gains the rec|ucsicr lhrc‘c features of that 
transfer, namely guaranLeed access to U8B bandwidth, 
inciiKiing latency bounding, guaranteed data rats through ihc 
pipe as long as there is data to deliver, and no retrying of data 
delivery in case of error. (Tfiis may sound odd at first, hot error 
recovery lakes time, extra packets and bandwidth. This mean.s 
that during error recovery, keeping the guarani eed bandwidth 
available is difficult, so error recovery Ls ignored.) 

Isochronous data is iransferred via a stream pipe, with 
no structure imposed on i! by the USB. Since this is a .stream 
pipe transfer, isochronous data flows are unidirectional as 
well. Maximum data payload sizes are established by the 
endpoints of an istKhronoys pipe within the limits of tlic 
bus speed for that pipe, (1023 bytes for full - speed, and 
1024 bytes for high - .speed.) During configuration, the USB 
.system software tries lo ensure there is sufficient bandwidth 
for tlie maximum data size of the transfer If lliere is, only 
then is the configuration eMahiished. 
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Isochronous transfers are limited to full/high - speed USB 
intplementations, and USB limlLs the percentage of a 
(micro)frame that can be used for isochronous transfers at 90% 
for full * speed transfers, and 80% for high - speed transfers. In 
general hosts must not issue more than one transaction per 
(mic:ro)fmme, tmless the endpoint is high - speed and liigh ■ 
bandwidth, which allows for multiple transactions per 
(micro)frame, and a maximum speed of 192Mbps. Due to 
limitations in the USB bus frequency and (miertOframe timing, 
no mt>rc than 151 full - speed one byte data payloads per fi'amc, 
and no more than 193 one byte payloads per microframe for 
high - speed transfers* 

To allow for guaranteed bandwidth in isochninous 
transfers, tlicre is no error retransmission on the bus. ThLs 
means that things like handshakes arc not used either. Basically, 
it is assumetl that all Isochronous data iransfeni succeed. 

The lliird type of data transfer is the Interrupt transfer This 
is used for devices that don’t need to send data often, but 
require bounded service [X*riod.s for iheir data transfers. 
Characierisiics of an interaipi transfer are a guaranteed 
maximum service jxrritxl for the pipe, and a retry of transfer 
aiiempts for failed delivery dunng die next service pericxl. Like 
isochronous ininsfers, interrupt transfers use stream pipes, and 
have no structure imposed on them by the USB, Tliey are also 
unidireaional. 

Data payload size limitations for ifiterrupt tmnsfers are 8 
bytes for low speed transfers, 64 bytes for full - S[xx*d transfers, 
and 1024 bytes for liigh - sfx^ed transfers. As well, high - sjx^ed 
transfers can request two or three transactions fxr microframe. 
Tile maximum size in an interrupt transfer is determined during 
device conOgiiration, and remains r'on.stant for the life of that 
configuration. If there is sufficient bus time for that data payload 
size in the assigned period, then the configuration is established. 

iTatiie usiige maximums for interaipi transfers are limited to 
80‘^^l for high - speed and 9<)% for full/low - speed ininsfers. fer 
* frame one byte payloads are limited as follows: low; 10, full: 
108, fiigli: 134. Maximum data speed for high speed endixiinLs 
in an inieiTUpl transfer is 192Mhps. 

Bus access periods for interrupt transfers are determined 
by tile speed of the endpoint. Low speed endpoint periods 
range from 10 to 255msec, full - speed transfers need from 1 
to 255m.sec, and high - .speed period limes are based on the 
equation (2hiiii<-^fV‘il i )x]25 ps, where blnterval is a value from 
1 to l6. The [KTiods between access times will he no longer 
than determined by ihe configurarion, hut can he slMirten 
depending on bus needs. As well, the access period is only 
used U) check for IKP packets from the software client. If the 
access lime for an endpoint comes around, and there is no 
IRP packet, then the endpoint Ls not poOed. This avoids the 
overhead of polling endpoints with no data transfer neetls. 
Like iscxilironotis transfers, ihe maximum data rate for a higli 
- .speed endpoint is 192Ml)ps. 

Tlie fourth transfer type Is the Bulk Iransler. Tliis is for 
devices that need to move large amounts of data, but at irrc'gular 


intervals, and need to be able to gel as much l>andw'idt]i as 
possible. Characteristics of a bulk transfer include USB access on 
a bandwidth available basis, error rciransmissron, and 
guaranteed delivery of data, Ixii no bandwidth or btcncy 
guarantees. Since iJie tran.sfers are on a bandwidth available 
basis, die speed of the transfers is dcfxndent on available 
bandwidth. As w'ith l.sochronous and interrupt mursfers, bulk 
transfers use stream pipe.s, are unidirectional, and luive no USB 
- imposed structure. 

Packet sizes for bulk transfers arc 8, 16, 32, or 64 bytes for 
full speed endpoinis, and 512 bytes for high - speed endpoints. 
Low speed endpoints do not use bulk transfers. If a data payload 
is not exadly one of the u.sable sizes for the endpoint, there is 
nt> ref|uirement for patiding the data out to those sizes. This also 
applies to isochronous and interrupt tran.sfers* 

When an endpoint needs to use a liulk transfer, it cannot 
Teserv^e' bandwidth, ala isochronous, nor can it reserve an 
access time, ala interrupt. The USB notes the size of the 
transfer, the speed of tiie endpt>ini, and makes the best effort 
it can to move the bulk tran.sfer data as fast as possible given 
the conditions on a specific bus. Essentially, bulk transfers 
get what is left over from iniernipt and/or isochronous 
transfers. 4he 1airnes.s' of this policy is determined by the 
Host Controller. Due to the way hulk transfers work, clienl 
software cannot, and .should not assume any specific speeds 
or access times for this transfer type, nor sljould it assume 
any pariicuLir order witli regard to conirt>l transfers. 

Bus frequency and frame timing limit the data payloads 
for bulk transfers to less ijjan 72 full - speed eight byte 
payloads ami less than 14 high - speed 512 byte payloads. 
Regardless of payload size, bulk transfers do not guarantee 
that Ihe payload will he delivered in any number of 
(micro)frames. Duq to USB conditions, u transfer could be 
spread out across multiple (micro)frarues, even if it is small 
enough to fit in a single fmicro)fr:ime. As with isochronous 
and interrupt transfers, maxim uni speed for a high -speed 
endpoint is 192Mbps. High - speed endpoints can have 
betw'cen one and three transactions per microframe to 
support high - bandw idth endjioims. 

Regardless of ifie type of tiansfer, lliere Ls a great deal of 
management that (xx'urs to en.sure that the USB funcUons 
smoothly, and efficiently. To fiand!e this (ask, there are a number 
of USB entities that shared the load of transfeT management, 
mainly tlie clienl software, the LI8BD, and the I (CD. 

One of Lite critical tasks in bm management is obviously 
transfer management. To ensure lliai alt Ininsfers are serviced 
correctly requires that the various USB enlilie.s work in a 
coordinated fashion. The first of the.se entiiie.s is the client 
.soitware, which determines w'hat transfers need ro be made 
W'ith a given function. It makes use of the appropriate 
openiting system interfaces ro request [RRs, ensures tlie proper 
pipes are used for the various transfer types, and helps manage 
the requirements of tlie different transfer types. All reejnests 
made by client software are presented via the USBD interface. 
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Aaother companent involved with transfer management is 
the USB Driver^ which is involved with bus access mediation, 
primarily during device aitadiincni and normal transfers. During 
attachment, the USBD is involved with making sure that a 
desired conOguration wdl actually be able to function on a given 
bus. if Lite configuraLion can l)e used, llien the IJSBD creates die 
appropriate pipes for the different transfer ty|)es, and deals with 
tilings like bandwidth allocation, etc. USBD chamcteristics are 
ii-siially heavily OS - dependent. 

'Hie IICD ensures tJiat all IRPs area tracked correcdy, and tliat 
bus bandwidth and (niicro)frame time niaxiniums are never 
exceetled. Tlie HOD maintains tlie tran.sacdon list for the various 
IRPs on a given pifx:, and liandlcs client noLification of armpleted 
IRPs. The traasaction list Is simply a list of all outst^inding 
transactions for a USlk Hiich entry in the list contams the 
transaction description items, such as data sizes, devic:e address, 
endpoint numliers, etc. 

'the host cx)ntro!ler uses the I ICD's transaction list to aeate 
I he appropriate tririsactions on the USB. The host controller also 
provides the importing mechanism for transaction status tracking, 
'llie ho.st controller ensures that various bus acc’ess rules are 
olieyed, such tis timeouts, inter-packet timings, etc, and works with 
tlie HCD to determine if a new can acees.s the USB. 

Another bus management issue is proper liandling ol' 
Isochronous transfers. Remember tliat these transfers are time 
dependent, and have no error t:orreaion, so easuring rdiahiliry 
is important. One of the key components in tills is die device 
itself, It has to provide the device descriptt)rs so that the 
isochronous transfers it will need can be set up correctly. 
Because there is no error retry in an iscKhronous transfer, both 
end.s of the transfer must lie lioth time and data - synchronized 
so that robust delivery of the data is achieved. Normally, this is 
done via a well defined clock system. 

Because USB is implemented on such a wide amiy of 
hardware and software, a single clock sjxxification wouldn r work. 
Instead, USB defines a ckxk model that various systems c^in 
adhere to in die lx^sl way for that system. There are multiple (^Itxrks 
provided by the USB to help with this. Tlie first is the Samjjle 
Clfxk, which determines the natural data rate of sample moving 
between the host's dient software, and various functions. The Hus 
Ckx'k is either a IKII 2 duck on full - S[)eed segments, or 8KJ Iz 
ckxks on high - speed segments. In a USB, the bus clock is usually 
a lower frec|yenLy iJian the .sample ckK:k. Tlie third dex^k used Ls 
the Service Clock, and this is detcniiined hy die rate die client 
software ains at to service accumulated 

To ensure I hat a l>road range of iscx'hronous transfers can 
handled, djere are often multiple samples used so that the transfers 
aren t intemipted for every sample. The multiple ,saniples are 
negotiated ahetid of time, so that the host controller can set up the 
most appnipriate one for use. Although the bus dock is intended 
to act as a master dock, real-time data needs make locking to diis 
clock impossible. However, since die data on the bus is 
packetizecJ, it is easy to just move one unit of data once per 
(micro )frame, as die (micro )fni me dock is reasonafily precise. 


The USB also provides a frame work for isochronous 
devices that defines synchronization types, (such as 
asynchronous, wiili data rate Feedback, Syndironou.s, locked 
ro the USB SOF rate, and Adaptive, using feedback, or data 
rate infbrination), methods for endpoints to provide data rate 
feedback, and connectivity re()uiremems. Endpoints are 
classified here by tlieir capability to synchronize their data rate 
to the date rate of the endpoint at the other end of the 
connection. The endpoints provide feedback by indicating, 
relative to the SOF frequency, wliai their data rates are. 

If a device is asynchronous, it cannot be locked to either 
the SOF rate, or any of the USB clocks. Therefore, they clock 
at either a Fixed data rate, one of a limited set of data rates, or 
a single, continuously programmable data rate. Asynchronous 
devices must report their programmatic capabilities during 
endpoint initialization. Their data rate is then hxked to either 
an external clock, or a free-running internal clock outside of 
the usual three USB clocks. 'I'hese devices still have to deal 
with data rare marching, but it is done elsewhere in the USB 
environment. The asynchronous devices carry their data rate 
as an implicit part of their sample rat, and must provide 
explicit feedback information to adaptive drivers. 

Synchronous devices t an have their ckx'ks controlled via .SOF 
syndironizaliun. These endpoints slave tlieir sample clocks to tlie 
1ms clex'k Lick via a prognimma):>le phase - lock - loop, (FLL). 
Like iisynchronou.s devices, synchronized endpoints can nin at a 
single fixed data rale, one of a limited number of data rates, or a 
continuously programmable data rate. 

Adaptive devices are the most flexible isochronous 
endpoints. They can send data at any rate in their operating 
range, and synchronize via constant ctmimunications on the 
bus. The data rate is eml^edded in the data stream, and can 
be adjusted on the fiy during the transmission. 

Conclusion 

Well, there Ls a lot of information about USB here, and I 
haven't even come close to dealing wiih all of it. To get all of 
the information, including tlie source documents I used for this 
article, please go to http://w'ww.Lisl>.org/ There is a wealth of 
infcxmaiion there tliat is of use to anyone wanting a greater 
understanding of USB 2.0 While USB 2.0 is not nearly what the 
people liyping it say it is, (and what ever meets its own hype?), 
it is a very capable upgrade to a .solid .standard, and should be 
a very capable partner along with FireWire in making connecting 
devices to our Macs faster and easier. 
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APPLESCRIPT 


By Bill Cheeseman, Quechee, V7' 


AppleScript Studio: Implementing an 
Application Preferences System 


Saving and Retrieving Application 
Preferences in AppleScript Studio 

We provided an overview of ApjileSeript Studio in the first 
anicit* in this series^ AppieScript Studio: An Introduction. In the 
second and diird articles, we will work with Sir Arthur Conan 
Doyle to solve the mystery of (low to create, ojieii and save 
dcx:uments in AppleScript Studio, t'he existing documentation 
dtxjs not cover Uiis, but an important clue suggesting that it can 
he done Is already in tlfe evidence room: one of llic three 
standard AppleScript Studio templates is named "AppleScript 
Document-based Application/’ Although the Watson example 
lluU forms the l>asis of tfie AppleScript Studio lutorial uses this 
template, neither it nor any of the other examples actually 
addres^ses the mystery. In the course of our detective work, we 
will therefore help Sir Arthur to write an example applicarion of 
his own. We will name it ‘"Doyle” in liis honor, carrying tlic 
current fad of naming applications after Sherlock Holmes 
charat lei's to iLs logical conclusion. 

The Doyle application will need a preferences file. The first 
solution an AppleScripter tliinks of when the subject of 
preferences comes up is to use a properry. However, the Release 
Notes for the first vcrsic)n of AppleScript Studio mention that 
AppleScript properties do not retain changes to their values 
Ix^iween relaunches of the applicarion. 'fhis Ls contrary to the 
normal behavior of AppleScript properties (and, for that matter, 
of AppleScript glol^al varial>les, which also retain their values 
across repeated launches of a script or .script application). A 
future release of AppleScript Sturlio will presumably restore the 
]>ersisicncc of AppleScript properties. In Lite meantime, the 
AppleScript Studio Release Notes recommend that ""if you want 
persistent storage of values, write them to a preferences hie.” We 
will therefore include in Doyle tlie ability to create, open and 
save a preferences File, which provides a simple introduction to 
the use of doaiments in AppleScript Studio. 'I he exercise will 


prove valuable even if properties eventually resume their 
accustoined behavior, since preference hies can be useful in any 
application of even mode.st complexity. 

We will latrkle the mystery^ of d(x:iiments in two installments. 
In die first installmcm, we will devise an ApplcScripl-ha,scd 
preferences system tn response to the injunction in tlie Release 
Notes. In the second, we will expand the example application to 
handle more complex dmrumcnLs. 

Unlike Sir Arthur's novels, the current mystery does not have 
only one solution. 'Ihere are many ^^'ays to save and retrieve 
information in AppleScript Studio, as in Cocoa applications 
generally. Tills article offers one solution among many. 

1 liis article and the next will include complete listings of tlie 
AppleS<Tipi staremenrs in the Doyle application. In order to keep 
the scripts as simple as possilile, we will make no attempt to deal 
with iniemationalization and localization, and we will do no 
error trapping. 

The AppleScrifi Document-based AppucAnow Templai t: 

The First step in writing any AppleScript Studio application 
is to create a new project in Project Builder, using its File -> New 
Project menu item to select one of tliree standard templates. Do 
this now, and choose the AppleScript Document-based 
Application template. Save our new project under the name 
“Doyle” wliercvcr you keep your scripting projects- your 
Documents folder will do, 

Before deciding what we need to add to the template, it will 
lie iLscfu! to build and run the lemplate as is, without any 
changes, to see what already works. Do this now by clicking die 
Build and Run button in Project Builder. An empty window 
named “Untilled” appears. This is in accord with the Atjua 
Hurrian Interface Guidelines, wtiich specify dmt launching an 
application or bringing a ainning application to die front (for 
example, by c:licking its icon in the Doc'k) should open a new, 
untitled window if a window Ix^longing to die applicatian is not 
already open, and it should deminiaturize a window if the only 


Bill Cheeseman is a retired lawyer now making his living as a Maciniush developer and loving every minute of it. He b uniquely qualified to write 
aboLii AppleScript Studio, having served as webmaster of The AppleScript Sourcetxiok (www.AppIeScfiptSoua^book.com) for many years and having 
also written a Cocoa tutorial, Vermont Recipes - A Cocoa Cooklxjok Cwww.siepwi.se.ct)ni/Aitit:lesA'ermonlRecipes/). 
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open window is currenily miniaiuri^etJ in die f>oi:k. 

Tile new window contains no controis, but our application 
docs have a menu bar, so let's try out some of its menu items. 
About Application, under Uie Application menu, hrin^^s up an 
About dialog. Like several of the menu items, tite Alxjut dialog 
contains dummy information. We will shortly customize the 
menu items and die Alx>ut dialog using Interface Builder, but we 
won’t liave to write any scripts to make them work. Help -> 
Application Help brings up a dialog stating that the application 
dcx^sn'l have any lielp. Well leave that alone in these two 
articles. 

The menu that interests us in these articles is the File menu, 
with its built-in New, Open, Close, Save, Save As, and Revert 
menu items. Try them out. Chtx>se File -> New; a new empty 
window appears, named "Untitled 2^ ChcK)se File -> Close; the 
new window^ closes, leaving the original “Untitled" window in 
place. ChcKJSC File -> Save or Save As; a standard file saving 
sheet opens with all the usual leatures, allowing us lo give the 
drxmment a name and select a location where it should Ix' 
saved, Tliis is getting worrisome, for it is Ixginning to appear 
that there may lx no mystery for us to strive! 

Crmiinning with the inve.stigation. name the untitled 
window "Test'' and seled your Documents folder as the place to 
save it. Another sheet promptly appears, saying “Couldn’t Save 
Document." '"Aha!" says Sir Arthur, “Here’s a mystery. Holmes 
will have to write a .script or two to save this dtx.'umem." 

Laying niii Groundwork 

Before figuring out how to save the document, we will liave 
to lielp Sir Arthur decide why Holmes woiiki want to save it in 
the first place, by specifying a task that retjuires saving and 
retrieving informatkxi. Let's have Doyle (llie applicaikm) save a 
log dix’umenting the course of the mvestigation, recording the 
date and time of every iKcasion when a ust!r LiunHies or quits 
Doyle. To make it more useful, well also allow the user to open 
the log and edit it by adding comments to each entry'. In case* 
stxiie detectives prefer to let the evidence .speak for itself, we’ll 
also give Doyle a Preferences window' in which the ability to 
edit the log can Ix turned on and off. It is this last feature, the 
Preferences window, that we will tackle in this article, leaving 
the Doyle Usage Log lo the next inslalimenl. 

’the basics of building an AppleScript Studio application are 
covered well in the dex uruentation and need not be repeated 
here except in brief outline. 

First, customize the menu bar. With our new Doyle project 
opim in Projeci Finilder, mouse over to the Groups ik Flies pane 
on the left side of ihe projeci window, selecting the Files tab if 
necessary to open it. Expand the Resources group, and ilouiile- 
dick MainMenu.nib, one of the files that comes with the template. 
Interface Builder launches and opens the new application's rrmin 
menu. Following the stejis outlined in ihe Apple^Scripr Studio 
dcx'umentation, change several of tlie menu items st) diey refer 
to “Doyle” instead of "Application.” Don't change the name of 
the Application menu itself, however; it will aiitomatkally take on 


ihe name of our applic.'ation when we run it. Don’t forget to save 
frequently and, when you're done, t:lose the MainMenu.nib file by 
clicking the MainMenu.nib window's do.se lx}x. 

Next, customize the About box. Click Credits.rtT in ilie 
Rcscjurces group of the Groups 8c. FQes pjine in the Project 
Builder window, and type any appropriate information 
identifying the team that built Doyle. 

Finally, dick fnfoPlist.strings in the Resources Group and 
]>rovide new values for the four variable.s you find there, 
following the model of the dummy strings in the template. 
Basically, just change “Application” to “Doyle” wherever it 
appears, and change the name of the author in the copyright 
notices so that some fake company doesn’t get credit for our 
work. 

Designing ihe Winikiws 
T he Doyle Usage Log Window 

Although the details of Implementing the I3oyle Usage Log 
will lx.* left lo the next in.stallment, we will design the main 
document window now to give us a seri.se of our a[ipliL:aiion's 
kxik and feel. Doubleclick Document.nib in the Project Builder 
window's Resources group to open it in Interface Biiilden If you 
don't see the empty dtxument window at first, double-dick the 
Window icon in the Instances ]iane t>f the Document.nib window 
lo bring it lo ihe front. Also, for Cfirivenience you can open the 
Info panel now by dioosing Tools -> Show Info. It i.s veiy helphi! 
to have this panel open all the time; for ihis reason, an InLerfiice 
Builder preference exists to Show Info Window at Startup, but it is 
turned off by defaiili. 

Witli the dtKument window open and selected, use the 
Attributes pane of the NSWindow' Info panel to set the window’s 
title to “f>nyle Usage Uig.” Also, select buttons and checklxixes 
in the lnft> panel as needed to set the window's Backing to 
Suffered, its Controls to enable Miniaturize, Close and Resize, and 
its Options to enafile Visible at launch time, Deferred, and One shot. 
TIjc meaning of most of these settings la obvifHis from their 
names. You will rarely, if ever, need lo change die default 
settings of thost* whose meaning is not obvious. 

From the Cixoa-Data palette, dnig a table view into the 
document window and [iluce it near the lop left corner, u.sing the 
Aqua guides to ixisition it precisely in accordance with the Aqua 
Ihtmcm hUcT/acc* Drag the table view’s bottom right 

resize handle to make the Udde fill llie waiidow to the right Ac|Lja 
guide and far enough from the bottom to leave room fora row 
of burtons. There i.s no Aqua guide to le:ive yoom in advance for 
die buiions; you will have lo Rratijtisl the table view^ in a 
moment, after adding a button. Create a iliird column in the tafjle 
view and name the columas, from left to right, “Dale," “Action," 
and “Conimcnis," using tec hniques descTibed in the AppleScript 
Studio documentation. Also, size the left column lo liold a cLite 
and the center column to hold the word “Run” or “Quit." Finally, 
select checkboxes in the Info panel to set the table view's 
Seiettion to Allows Empty Selection, Allows Multiple Selection, and 
Allows Column Selection, its Scrollbars to Vertical and Horizontal, 
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anti its Options to Allows Resizing, Display Column Headers, 
anti Autoresizes Columns to fit. Other items sliould be deseleeteti, 
including Allows Reordering because we want the log to remain 
in chronological order 

Dmg a stancbird push button from the Cocoa-Views paletre 
to a posihon near the bottom right comer of die document 
window, lining it up with the aid of tlie Aqua guides. Name the 
button “Delete.'* 'the button rmiy resize itself to acconunodiite 
the length of its new LillOj so you miglit have to readjust ils 
position afterwards. You can also now drag die btitloin edge of 
the table view to position it the proper distance above the 
button, using the Aqua guides that have now become available. 

The Preferences Window 

Now we are ready to design the Preferences window. Close 
Documentnib to get il out of the way for now i>y clicking iLs close 
box, saving it if asked. Still in Interface Builder, choose File -> 
New; the Starting Point dialog opens, if it wasn't already open. 
Select Empty under the Cocxia topic and click the New l>uiion. A 
new. untitled Interface Builder nib window opens, with die 
Instances pane selected and containing File's Owmer and First 
Responder icons. Foi' convenience, save it now, before making 
any changes, by c}KX)sing File -> Save As. Give it the name 
“Preferences, nib*’ and navigate to save it in the English.lproj 
subfolder of the Doyle project folder. I.eave die checktxix 
unselecLed so diat the file cxlension will nciL be hidden. When a 
sheet ap[Xiars, click die Add button to add the new nib file to 
the Doyle project and target. If diis sheet does not appear, you 
saved the nib file in the wrong place; this can easily be cured by 
using Project Builder's Project -> Add Files command, preferably 
first dragging the new nib file into the correct location using the 
Finder in order to keep all the project files in one place. After it 
appears in the Groups 8i Files pane of the Project l^uilder projeci 
window, it is convenient to drag it into the Resources group if it 
isn't already there. The sniail checkbox to its left should lx? 
.selected, indit^tdng that die file will lie included in the target 
when the application is built. 

Select the Filers Owner icon in the Instances tab of the 
Preferences, nib window and, in the Atlrihutes pane of die File's 
Owner Info panel, select NSApplic^ition to make the application 
object the owner of this nib file, li' a dialog appears warning you 
that something evil will happen, you haven't succeeded in 
adding ilie Preferences.nib file to tlie project. You can proceed 
with the design of the window anyway, but be sure you 
remember to add the file to the projeci later using Project 
Builder's Project -> Add Files command. 

Drag a window teem from the Ckjcai-Windows palette into 
the Instances pane of the Preferences.nib window. A Window icon 
appears in the Instances pane and an empty window appears on 
die screen. Using die Attributes pane of the NSWindow Info 
panel, give die window the title “Preferences” and configure its 
settings as you did with the document window, with these two 
exce]>tions: the Resize checklxix in the Controls area should l^e 
deselected, as should the Visible at launch time checkbox. 


Finally, dmg a checkbox (or "switch,” as it is sometimes known 
in Coc'oa) from die CcKxxi-Views palette to die top left comer of the 
Preferences window, and rename it “Show Comments in Usage 
Log.” 1hen, resize the window to make it sirxiller, until die right 
Aqua guide indicates that you liave the correct margin on die right 
and until the lx>ttom edge is iis close to the top as you are allowed 
to drag it. Widi the checkfxix still selected, use the NSBiitton Info 
panel to select the Selected checkbox in the Options arcra^ We will 
set the Show Comments in Usage Log preference to true by default 
m one o( Doyle's scripts in just a moment. 

Save the Preferences.nib file but leave it open. We are now 
ready to start scripting. 

Scripting the Appucation 

We will start by scripting the PrefcTcnces window, because 
il reflects a single value that must be read by the main document 
window before the latter is opened. We will set up the 
Preferences window and s^:^ipts for setting and getting its one 
preference value first. In subse^quent sections, we will take care 
of cocirdinating diis preference value and the user interface, and 
we will arrange to save this value to di.sk in a preferences 
document and retrieve it when die application is launclied. 

Managing tlie Preference Value 

We now have a Preferences window drat will allow the 
user, by checking or unchecking a checkbox, to specify 
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whether comment;; are to be shown in the Doyle Usage Log. 
Next, we need Lo provide a means to hokl this preference 
value—true or false— within the appliaition, so lliat it can be 
looked up every time the user opens tlie Log- An easy way to 
do this would be to rely on the state of the checkbox itself as 
a record of die state t>f the preference item, but we won't do 
it that way. !'or many reasons, data values should almost 
always be stored separately from the user interface. Here, we 
will save the value of the application's single preference item 
in a disk-based preferences file. 

We will not use Cocoa's built-in application preferences 
system, baseti on ihe NSlJs^^rDefault.s class, hut will instead store 
Doyle’s preferences as an AppleScript recemd using the 
Read/Write commands implemented in the Statidard Additions 
scripting addition. In the first release of AppleScript Studio, tile 
Ccxroa applicalion preferences system is not available to 
AppleScript- The AppleScript Studio engineering team ha,s 
informally made available a temporaty workaround for using it, 
in the expectation that AppleScript access to Cocoa's 
NSUserDefaults chess will become a Ijuilt-in feature in a later 
release. Even then, liowever, there may lie reasons to prefer a 
pure AppleScript solution, so w^e will develop one here. 

As the Apt)leSc'rit)i Studio documeniation very l)riefly 
suggests, it is geiierally a gexjd idea to follow the Model-Vicw- 
Contndler, or MVC, design pattern, whereby the Model 
(consisting of the appikaiton's data and data management 
algorilluns) is kef)L se[xiratc frotn tire View (the application's 
graphical user ioterhice). The MVC paradigm is particularly 
important in Cocoa applicaiicins, liecause the Cmoa frameworks 
arc built around die concept and depend upon it in a variety of 
ways. It may lx; less imjx)rtant in an ApjileScript Studio 


application, where the event handlers are already laid out 
according lo the AppleScript objett model and the strucRires of 
a C(K:oa application- We will nevertliele,s,s folkw the MVC 
pamdigiii here by storing and manipulating our single 
preference value in one script, called 
PreferencesModefapplescript, wliilc ccx>rdinating the preference 
item anti die user interface in a second script, 
PreferencesConlroller-applescript. 

If, after reading ih!s article, you adopt this system and create 
an apjilicalion of your own having many f)reference items, you 
will be thankful that you started out this way. It wilt allow you 
to keep all the preference item data and handlers to 
manipulate it in t>ne script, while is<>laling handlers to update 
the user interface and to obtain infonnation from tlie user alx^ut 
tile preference items in a separate script. Although it isn't 
necessary^ lo create separate sc:ripts in this manner in AppleScTipl 
Studio, getting in the habit of lorcaking scripts into smaller pieces 
according to some reasonable plan will help you to keep the 
.scripts ma nageable as your applicarion grows larger. Here, if you 
later cliangc the user interface, you will at ititxsl have to revise 
the Controller saipt; the Model script will continue to work 
witiiout change, likewise, if you later rearchitect die dara storage 
strategy, yoti will ai most have lo revise the Model stxipt but can 
leave the Controller script and the rest of the application alone. 

Our strategy for implementing these two scripts will be 
dictated by the fact that AppleScript properties and global 
variables do not retain their values across relaunches of the 
application, but the .strategy will work as desired even if this 
problem is repaired in a subsequent version of AppleScript 
Studio. We will save our preference item to a disk file 
immediately after it ts changed by the u.ser and retrieve it 
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from disk whenever il is needed. Every lime the application 
is launched, i! will look for a preferences file in a standard 
location. If it does not find the file there, it will immediately 
create a new one, setting its contents to initial default values 
coded into the application. If il does find a preferences file, 
it Will use the settings found in it, even if the settings it u.sed 
the last time it was run were different (ft>r example, the user 
might have substiiuied a new preferences file for the old file 
in the meantime). 

This strategy will be implemented in a new script, 
PreferencesModel.applescript. The script will include several 
handlers fur ojxming the preferences file, closing it, setting its 
initial default values if the file does nor already exist, and 
retrieving all of its values. In addition, il will include, for the one 
preference item implemented in this article, a ‘'get*' and a *‘sef* 
liandler to retrieve or change its value. Additional get and set 
primitives can be added laier, if additional preference items are 
needed. These are termed “primitive’" tiandlers, l>ecause they get 
down and dirty witli the underlying details of our preferences 
system. Later, we will call these primitive handlers from liigher 
level handlers implemented in the 

PreferencesControlIer.applescript, to intenia with the user. 

We will set the initial, or default, value of our one 
preference item to tnie in a permanent property, 
preferencesDefaultRec, to match the selected state of the 
cliecklxjx tliai we created earlier in the Preferences window. 
The property holds an AppleScript rec:ord, and additional 
labeled fields can l>e adcletl to il if additional preference items 
are needed. This default value will l>e u.sed whenever the 
application can't rind a preferences file. Strictly speaking, it 
wasn’t necessary to select the checkix>x in Inlerface Builder, as 
we did ahfjve, becau.se the ap|>lication will gel the default setting 
from this pro^x-Tiy in any event and update the checkhtjx to 
match, 'rhe property that holds the defauli preference item value 
will never lx* changed by our code, so iL will lx initialized to the 
original default value every time the application is launched, and 
the lack of jxrsistem property changes in this release of 
AppleScript Studio w^on'i matier. If we change the default, we 
will recompile PreferencesModel.applescript and it.s nerw value 
will diereafter remain as is until we again recompile. 

As descrilxd above, we will provide primitive liandlers in 
PrefenencesModel.applescript to initialize and to get and set the 
values of diis pro[Xiiy on clisk. These liandlers are intended Lt> 
be called from another script in the application, 
PreferencesController.applescript. However, liandlers in another 
script cannot lx called directly in AppleScript Studio. Instead, 
we have to resort to a simple strategy of indirection. We place 
each of them inside an explicit script ob[ect defined in 
PreferencesModel.applescript using AppleScript's Script keyword. 
In fact, the entire liocly of PreferencesModeLapplescript is 
enclosed in a script object, named preferencesModelLib. Any 
other script in our application that needs to call one of these 
handlers will use the Load Script cotnm;md from the Standard 
Additions scripting addition to load a copy of 


ProferencesModeLapplescript and store its script object, 
preferencesModelLib, into a property, prefsModelLib, declared in 
the calling script. 'Ihen the handlers of the kxided script object 
can be called by telling the ]>ro|^>erty in the calling script to 
execute any of lliem. 

Declaring a script object within a script, as we have done 
here, is sometimes recjuired in AppleScript, for technical reasons 
having to do with the context wtthin w^hich the script’s handlers 
are to be compiled and exeaited. For a detailed cxf)lanation, 
read the Script Objects c:hapler of the AppleScript Language 
Guide and a short article 1 wrote for The AppleScripi 
Sourcelxjok, Subroutine liandlers in Script libraries and Script 
Servers, at 

WWW.Si pplesc^ri pLsc m rcelxx )k.com/tips/sctiptserver. html. 

To create die new script, select the Preferences window in 
Interface Builder and go to the AppleScript pane of the 
NS Window Info panel. Click die New Script button at the bottom 
and save il as PreferencesModeLapplescript in the Doyle project, 
New AppleScript scripts can be created in this manner in 
Interface Builder or, as we will .see later, in Projea Builder. 

Now switch to Projc*cl Builder, where you will see the new 
PreferencesModeLapplescript file in the Scripts group. Select it, 
and, in the editing pane of the projecl window, type the script 
object and handlers shown in Listing 1. In AppleScript ja^on, 
this file is called a “script library," 'ITie use of script libraries is a 
common, if somewhat advanced, technit|ue in AppleScript 
generally. A script library function.s much like an “include" file, 
allowing propenies, handlers and odier AppleScript construas 
declared in one file to be used in another file through 
AfipleScript’s Load Script mechanism. 

Listing 1: PreferciicesModeLapplescript 

(’ Prcfm'JiccsMtKkJ.appIcWTipr') 

C'lliis is an MVC Modi'l s^cripr that manages the values of prtfertnee k 

pnjvides m inidaliiuiliun handler far all of them and gel ami sei accessors for each, as 
well as some uUlUy handlers. *) 

(' fniTial default values aa* set in the initPrcferenccs() handler, which is executed only 
if iHi preferences file is found at taundi.Otherwbc.the values of all preferences are 
obtainal from the piiefeferK:e,s file. A [rrcfeiences file is saved in the airrent user's 
Preferences foUkT at -/!jhrarv/Ptefcrences, The file is always closed immediatel)' after 
reading or writing in order to avoid corruption in the event of a exash. PlreferctRes arc 
saved arid managkl as a single A|iplcSiTipi reconl. Ernir checking Ls omitted. *) 

C l*rT>pertie-s') 

— Name of preferences tile 

property prefcrencenFileNaiiie : “^Doyle Preferences*' 

— Default preference record; this pmpert)' ma)’ not he changed by a aser. so it serves 

— as a pemuneni record of default values for initialization of new preferences fUes 
property preferencesDefaultRec : IshowComiaentGPrcf i tnjcl 

— Insert other fields in the preferenceslMauJtKec reatrd with comma delimiters 

— if additicjfial preferences are added, and recompile. 

C ScTipi Objects") 
script preferenc^sModaiLib 
C Hanaers') 

— 'Dicsc handlers provide access to preferences at die most primitive level. 

— Load this script object into another script and call these primitive handlers 
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— wtierever access to prefca^nccs is requiicd. If the prcfercaces io&astnictonc 

— LS later changed, only Um licripi will ret|uire rcvbion, so long as the 

— names and renim values these handlers remain unchanged. 

on openyceferencest) 

— Opens current user's prciprcnccs fik, creating an empty file if mvne exisLs. 

— Heiums path to current user’s preferences file for use in oilier handlers, 
set preferencesFiiePath to 

(path to preterenees from user domain as string) -> 
h preferene&sFileName 

open for access file preferencesFllePath “> 
with write perinlsKion 
return piefetencesFilePatb 
end openFreferences 

on closePreferencesO 

— C3om;s current user’s preferences file, saving changes, 
set preferencesFllePath to "> 

(path to preferences from user domain as string) 

& preferenccsFileName 
close access file preferencesFilePath 
end dosePreferences 

on initPreferencesf) 

— Sets preferences to default ralues if no preferences file exists, 
set preferencesFilePath to openPrsferencesO 
Lty 

read file prcferencesFilcPeth 

— discard if siicccssfiil 
on error number -39 

— end of file indicates (iJe is cniptj^ (just created) 
write preferencesDefaultRec to ^ 

file preferencesFilePath as record 
end try 

closePrefereneen() 
end initPreferences 

on getPreferencesRecord() 

— Returns die entire current preferences nx'ord. 

set preferencesFilePath to openPreferencesO 

set thePreferencesRec to ^ 

read file pteferencesFilePath as record 
closePruferences() 
return thcPrefcrcnCGsRec 
end getPreferenceaKecord 

on getShowCommentsPreference() 

— Retiuns current value of show conunents preference item, 
set thePrefctencesRue to gotPreferencesRecord() 
return showCommontsPrGf of thePreferencesRse 
end getShowCnnnneBtsProferente 

on fietShowCommentePreference(setting) 

— Sets new value of show eoinmeois preference item, 
aet preferentGsFllePnth to openPreferencesO 
aet thePtuferoncesRec to ^ 

road file preferencesFilePath as record 
set showComnmntaPrEf of theProforencesRec to setting 
set Gof file prefercncoaFilePath to 0 
— discaref old eciiitents of file 
write theFreferencesRec to "■ 

filG preferencesFilePath as record 
closePreferencesO 
c nd s otSh owC QiniBe nts P r e f e r enc e 

— Inst'rt additional aceessots on paiiem of geiShowf'ommentsPrcfertiiceC) and 

— setShowCommentsPrefefcneeCscttirtg) here if additional preference.H arc added. 

end script 

1 he cxlci character at the ends of some lines in Listing 1 is 
AppleScript’s tine continuation character, allowing us to split 
long lines into shorter segments so they don’t mn off the page 
to the right. In most script editors, it is possible to type the line 
continuation character and start a new line in one stroke by 
pressing Opijon-Rctum. In tliis release of AppleScript Studio, 
however, you must type Option-L followed by Return. 


After you have typed the body of 
PreferencesModelapplescript, examine each of iLs handlers. These 
are garden-variety AppleScript statements, using the Read/Write 
commands in the Standard Additions scripting addition. If you 
aren’t familiar with them, you can read about them in Apple's 
ScripHng Additions Guide or any of the several good books 
ahoiii AppleScript currently in print. 

Updating the User Interface 

Next, we need to write the 
PreferencesController.applescript script that will call the 
prbnitive handlers in PreferencesModet.applescript to get and set 
the preference item’s value, display it in the Preferences 
window, and accept changes made by tlie user. 

To cany out the Model-View-Controller (MVC) paradigm 
consistemiy, we will use this new script to hold the handlers tliai 
coortlinaie the user interface of the Preferences window with tlie 
value of the preference item. As its name indiaites, it is a 
Controller, the third component f)f the MVC trinity. The second 
component, the View, is essentially already written, in that 
ApplcScTipt Studio comes with many predefined view cia.sses, 
such as windows and user controls, with buili-in event handlers 
to take care of their basic functionality. By [)uiting handlers that 
LX>nirol liie state of the vaiiou.s View objects into a separate 
Controller script, we effectively isolate ihe View from the Data, 
llie Controller serves as an intermediary between the Model and 
the View and therefore must know alx)ut both of them. 
PreferencesModel.applescript, which is the Model holding the 
preference system’s handlers for accessing the data, knows 
nijtliing alioui the nature or features of the user mterfhee (the 
View), and the built-in Ctx'oa View objects knew nothing alx>ui 
the structure and implemeniaiion of the data they represent fihe 
Model)* For that reason, PreferencesModeLapplescript need not 
he changed in any way even if we completely revise the user 
interface. Only the Controller script will need to be customized 
if the user interface is tdianged. 

Go inU> Project Builder now and create the new script. 
Cl UK^se File -> New Fie. then in the New Pile assisUint select 
AppleScript File under ilic AppleScript heading and click Next, 
In the New AppleScript File assistant, name it 
PreferencesController.applescript and chek the Finish button, first 
making sure that ihe Icxation is set \a the Doyle project folder* 
If the new file appears elsewliere in the Groups ^ Files pane of 
the project window, drag it into the Scripts group. Type the 
property and script object shown in Li.sting 2 into 
PreferencesControllerapplescript. 

Listing 2: PrefereiicesController.appleseript 

C PrefCTcncctContrtilleT applcsc'ripi *) 

('This Is :iri MVC Ctmiroller iscripi Lhsit contaijis handlers to ciHintinate data values !n 
PreferentesModd.appkiieript with the user inlerfact- in the l^^fcrcntcs window. ‘) 

C Pn>p< rties *) 

property prefsHodalLib : null 
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c* Sclipi Objects *) 

script preferencesControllerLib 
C Handlers *) 

—These hamlkrs gri amt sti pfcicrraces using plain Englisii terminology, by 

— loading and calling die pritniUve liandkn In l^fcicnccsMtJdclapplest ript 

— if the prefca'iiccs infrasinicturc in l^fcrrnctJiModd.applescript is later 

— changed. Uiis script will not require revision, so long as the names and 

— return values of the primitive handlers remain unchanged. 

on inltPrnfsO 

1oadP fe ferencesMod eiLib C) 
tell prefaModelLib to initPreferencesO 
end InltPrefs 

on coramentsAreShownO 

JoadFcef ernnee.^Kodel L i h f) 
tell preffiModolMb to 

rnt urr get ShnwCotitRiont s Pre fetence (J 
end commen t MreShuvT) 

on shawCominonr&0 

losdPreferencesModelLib() 

teU prnfsModelU.b to setSho¥CoiiiinentsProforence(Lrue) 
end showCommentn 

on hldeCoDmientsO 

loadPrc fcrcnceuHodelLlb C) 

tell prefsModelLib to setShowCoraiBentsPreferenceCfalse) 
end hideCotnfflentS 

end script 

<* Handlers *) 



on loadPrnferenccsModelbibO 

~ loads PrcfercnccsModelLIb from Pt^ferencesMcHfcLapplciiCTtptJf not loaded. 

If class of prefsModelLib is not script then 
load script POSIX file "< 

((path for script ■’PtfiferenresModel" -> 
extension ^^sept”) of main bundle) 
set prefsHodelTJb to prcrercnccsModelLlb of result 
end if 

end IoadPreferencesModelLib 
Event Handlers ') 

“ See UsUnp 5,6. and 7 for the event handlers in tbh script, 

'Itie AppleScript handlers dial are enclosed in an explicit 
,stTipt object named preferencesConirollerLib in 
PreferenccsConin>iler.apples<TipT are the liighdevel handlers we 
referred to above, llieir names iniplcmeni Engl ishd ike grammar 
intended to facilitate their use in simple statements dial sound 
very like normal English sentences. Each of them first loads tlie 
script object in PrcferencesMcxlel.applescripr, if it is not already 
loaded, and then calls the primitive metlxxls implemented there. 
The higfi-level handlers are placed in a script object in 
PreferencesContrt^ller.applescTipt .so that they^ in turn, can be 
loaded and called by other scripts in Ute application, as we will 
see later. While rhi.s double layering of handlers is not necessary 
in an AppleScript Studio application, it is used here as part of 
our effort to separate the Mtxlel object from the View in 
acetxclance with the MVC paradigm. It echoes a Icchnittue 
commonly used in Ccxrva applications. 

Outside of the PreferencesControllerUb script object, 
PreferencesController.applescript implements one property and 
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one handler. The property^ prefsModelLib, will hold the 
preferencesModelLib script object from 

PreferencesModeLapplescript. It is assigned that value l>y die 
handler, loadPreferencesModelLib(), using the Load Script 
command from liic Standard Additions scripting addition. 

The loadPreferencesModelLibO handler uses a cc}mmon 
AppleScript technique to load the stxipt library only when 
loading is needed. Tt first tests the prefsModelLib property to see 
whether it is of die built-in AppleScript class, Script. If it i-s, we 
know dial the script library has already been loaded, because 
the prefsModelLib property was initially set to null in its 
declaration. This teclinique takes advantage of the fact that 
AppleScript properties and variables are not strongly typed; dieir 
type is the type of whatever value they currently hold. 
Therefore, we can call the loadPreferencesModelLibO handler tn 
every handler dial gets or sets a preferences value, knowing that 
the call will do nothing if die script is already loaded, in order 
to ensure that the script will always be loaded when necessary. 
A.S a bonus, if pro[iertie.s retain their values across relaunches of 
an application in a future version of AppleScript Studio, die 
script library will only have to lie loaded die first time the 
application is run after it has been compiled or recompiled. (The 
iiKxlcst execution efficiency this gives us on subset]ueni 
launches comes at the expense of stimc increase in file size. If 
this is an issue for your application because its preference 
sellings are very large, you c'an reset the prefsModetLib properly 
to null when quitting the application), 

'Ihe file holding the PreferencesModei.applescript script must, 
of course, be found liefore it can be loaded in this manner We 
know from the AppleScript Srudio docaimeniation and from 
examining built examples that the script files contained in an 
AppleScript Studio application bundle are located in a Scripts 
sulifolder in die Resources folder in tlie application bundle's 
Contents folder. One way to find these scripts, dicrefore, is to 
code this path explicitly into a handler. The only other thing we 
need to know Is the path to the mnning application, whic*h can 
be obtained from the Standard Additions* Padi To Me command. 
Also, the script’s file extension will clumge from “.applescrtpt’* in 
its text form to “.sept'^ in its compiled form. The 
pathToPreferencesO handler in Listing 3, using this technique, is 
cribbed in pan from several of the AppleScript Studio examples. 

Listing 3 

on pathToPreferencesHod^iC) 

set appPath to (path to me froiii user domain) as text 
return (appPath i “Contents:ResourceE:Scripts;") as text 
end pathToPreferencesModel 

on loadPreferencesModelLibO 

if class of prefsModelLib is not script then 
set prefsKodelLib to load script file ^ 

(roy pathToPreferencesModelO k 
"PreferoncesModel,sept") 

end if 

end loadPreferencesModclLib 

*11iere is a more flexible means to aectiinplish the same end, 


however, using siiecial features in AppleScript Studio's 
dictionary. The Application Suite in AppleScriptKit.asdictionary 
includes a Path For event that remms the palh to any of several 
special AppleScript Srudio Itx.-ations, including the location of a 
script in tlie application bundle given its mime and its compiled 
file extension. Similar feamres are provided in lire Bundle class, 
whose properties provide die paihs to important components of 
an application liundle. Here, we use Path Far in conjunction with 
the application objea's Main Bundle properly, which will 
hopefully give our application a more robust capability to 
survive any future changes to the location in which scripts are 
iiundled in some future version of AppleScript Studio. 

Tliere is a wrinkle to using the Path For event and die similar 
class properties: they return folder and file paths using the 
forward slash charaaer as a delimiter, as required by Coeexa, 
whereas most AppleScript commands, such as the Load Script 
command in Standard Additions, raiuire the colon character as 
a delimiler. Fortunately, AppleScript L8, included with the first 
release of AppleScript Studio, contains a new POSIX File elas.s 
and a POSIX Path property to make it easy to convert file paths 
between the slash-delimited POSIX form and the colon- 
delimited AppleScript fonn. 

A step-by-step version of our loadPreferencesModelLibO 
handler using the POSIX Path property is set forth in Listing 4. 
Note dial die Path For Script command takes a second parameter, 
Extension, which is not documented in the manual or die 
AppleScriptKit.asdictionary. Its usage can lx: gleaneLl Ifom one of 
the examples; using path for script "Preferences.sepf will not 
work. Note also dial we do not have to bracket Main Bundle in a 
Tell Application block, because this is a.ssiimed in AppleScript 
Studio. (The final version of our load Preferences Model {) handler, 
telescoping the first three lines of the If clause in lj.sting 4 into 
a single statement, can l>e seen in listing 2.) 

listing 4 

on loadPreferencesModelLibO 

if class of prefsModelf.lb is not script then 
&et (path for scripl "PreforencesMndel" -« 
extension "sept”) of main bundle 
get POSIX file result 
load script result 

set prefsModelLib to preferencesModelLib of result 
end i f 

end loadFreferGnccsModclLib 


Ctmnectlng Event Handlers 

As wrilten to this point, our scripts will do nothing, liccause 
none of the handlers we have wriiten has yci lx.'cn "^coimeaed” 
to an AppleScripi Studio event handler. This is a fundamental 
lesson lo be learned m writing AppleScript Studio applications. 
No AppleScript handlers will be executed unles.s they are eitlier 
directly connected to an AppleScript Studio event handler using 
the AppleScript pane in the interface Builder Info panel, or 
unless they are called (directly or indirectly) from a handler that 
is connected to an event handler in this manner. This is why» for 
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example, a Run or Reopen handler in an AppleScript Studio 
script will never be called, even ihough it will compile because 
these events are pmper AppleScript syntax: there is no Run or 
Reopen event in AppleScript Studio, so we can't connect them. 

Event handlers are connected using Interface Builder- 
Before switching to Interface Builder to do this, liowever, we 
must first save our project in Projea Builder. Due to the way the 
first release of AppleScript Studio is set up, there is a risk that 
we will lose most or all of our scTipLs if die aren’t saved before 
switching to Interface Builder and connecting new event 
handlers, "llieretbre, compile and save the project now. 

The first event handler we will connect is Choose Menu Item 
in MainMenu.nib. The user of Doyle must have some means of 
opening our Preferences window in order to review and set 
preferences, and in Mac OS X this is normally done l>y choosing 
the Preferences menu item in tlie Application menu. In Interface 
Builder, open MainMenu.nib and, if nece.ssary, double-click the 
MainMenu icon in the Instances pane to open ihe menu bar. 
Click the Application menu on the left to open it, and see that it 
contains a Preferences menu item. If we were to compile and 
Rin the application now, we would find that this menu item is 
disabled. In order to enable it, we will have to conned an event 
handler to it. Click on die Preterences menu item to select it. 
dien, in the Appleiicript pane of the NSMenultem Into panel, 
click Choose Menu Item tinder the Menu group in the Event 
Handlers area, click PreferencesControllerap pi ©script in the Script 
area at the bottom, and click the Edit Script button. A new 
Choose Menu Item event handler appears in 
PreferencesController.applescript in Project Builder. Fill in the new 
event handler wiili the statements shown in Listing 5 (die 
ellipsis, or three dots, are typed by pressing Option-;). 

listing 5 

on choose meny itejD theMenuIteta 

If title of thcHenuTtcra Is ^'Preferences^** then 

lead uih “Preferences* 
end if 

end choose menu iteai 

Although not necessary at this point, we enclose the Load 
Nib command in an If block checking rhe name of the menu 
item. This will make ii easier to connect t>ther Choose Menu Item 
event handlers in this script in the future, if desired. AppleScript 
does not allow overloading of liandlers, so scripts cannot 
contain multiple handlers having the same name, even if the 
dircti parameters differ. Being limited to a single Choose Menu 
Item event handler in any one script, we have to test the 
parameter tn chained If/Else clauses to find the one menu item 
that the user chose. 

Tliis event handler causes the Prefereni^s.nib file to be 
loaded (notice that the “.nib" file extension is omitted), whit:h 
will cause the window that we designed in Inlerfacc Builder to 
open. However, it will open invisibly, so we will have to tell it 
to become visible after the nib file has been loaded. 
Eurthermore, we should set the visual state of its u.ser contnils 


to match the state of ilie prefcrencus file before making it visible, 
in order to avoid unsightly flashing. AppleScript Studio invokes 
a Will Open event handler whenever a window is about to open, 
so we will connect that event handler next. 

Ikrfore switching to Interface Builder, save the project file to 
ensure that our scripts will not be last. In Incerfice Builder, open 
Preferences.nib and, if necessary, double-click the Window icon 
in die Instances pane to open the Preferences window. Click in 
an empty area of the Preferences window to select it if 
something else is currently selected. Then, in the AppleScript 
pane of die NSWindow Info panel, click Will Open under the 
Window group in the Event Handlers area, click 
PreferencesController.applescrripi in the Script area at die 
ixmom, and dick the Edit ScTipt liution. A new Will Open event 
handler appears in PrefefencesController.applescript. Eill in the 
new event handler with the sLitemenLs shown in Listing 6. 

Listing 6 

will open thaUindou 

If title of theWlndow Is “Prefefences" tlien 
set state of button I of theWindow 

to prefetencesCcmirol 1 erLib '0 cotnmentflAreShovn() 
set visible of theWindpw Lo true 
end if 

end will open 

nils is the first time we have culled a handler dial resides in a 
scTipt object. Here, wc do so I>y cjualifying the call with the 
jxissessivc fonn of die saipt object's name, preferencesControllerUb’s; 
we could as well have used AppleSc^ript's alternative syntax, of 
preferencesContrallerLib, or a tell preferenoesControtlerUb block, nie 
single diccklx)x in the Pieferences window is button 1 of thit 
window (in (locoa, a checkbox is implemented as a fonn of button), 
and we want to set its State propeny lo checked or undiccked, 
acc:ording to the cuiTeni value of die preference setting. The 
preference setting is saved as a true or false value in AppleScript 
terms. Although the Oxm dcxiimentation iclls tus that a diccklxix 
button's State v^aliie is an integer, aipahle of taking any of die ViUues 
t, 0, or -1, C^'oa allows 1 and 0 to lie nepresented, mspeoively, as 
YES or NO (true or false), tin Okxki, -1, or die constant 
NSMixedState. nepmsemts a mixed-state dieckfiox, [xirtmyed with a 
dash in die checkbox instead of a checkmark.) We therefore get the 
return value of the oommentsAreShown() handler in the 
preferenc^ControllerLib .script olijcct and set die State of die 
dicx:klx>x to die returned Boolean value. Since die script object is 
Ixidi declared within and C4i!led from 
PreferencesController.applescript, it isn't necessary to use die Load 
Script aimmand lo It rad it. 

We know, from the work we have clone so for, dial invoking 
the commentsAreShownO handler cuascs 

PrBferencesC)ontrc>fler.app!escript to load die preferencesMcxtelLib script 
objeca in PreferencesModel.applescript into the PrefsModeiLib 
property, if it isn) already loaded, and to tell the PrefsModeiLib 
property^ to execute its GetShowCkimriientsPreterer^ primitive 
liandler, and Unit die latter in turn reads the preferences file from 
disk, pulls out die value of the desired preference item, and returns 
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ii. All of Itlifi happc^ns in a Iricc. Tiicn, when the Visible propaty t)f 
die window is set to tme, die window appears on screen, with a 
checkniark in die checkbox if the preference value on disk was tme, 
Tlie final event handier needed by 
PreferencesControllerapplescript is a Clid^ed hitndler to ujxlate die 
wdue of the preference on disk wlien the user clicks the cliecklxix. 
Giaxa aulontaticrally supplies the eliet:kmark when tije u,ser elieks. 
Willi Preferences,nib still Ofien in Interface Builder, click on die 
diecklxix to select ir, dien go to the AppleScript pane of die 
NSButton Info ptmel. In the Action gniup, chtx'k ihe Clicked event 
iiandier, iind cheek die PrefereneesControllenapplc*senpl script near 
die lx)ttoni, dien click the Edit Script button. In Project Builder, till 
in die new Clicked handler acmrding to listing 7. 

Listing 7 

on clicked theControl 

if title of theConttol is 

"Shew CcHntiients in Usage Log" then 
If atate of LheConttol is 1 then 

tell pceferencesControllerLib to showCotimeritsO 
else 

tell pceferencesControllerLdb to hideCommentsO 
end if 
end if 
end clicked 

By now, you can trace out for yoursell’ exaaly how this works. 
We assume thiit, tf’ the state of die checklx>x is not 1 (tme), tlien it 
musi lx* 0 (liaise), lxx:au.st; we do noi make use: of the available third 
state of a Gxoa cliecklxjx in Doyle. 

There is still one important thing missing from our 
preferences system: the preference Hie dcx*sn't get initialized to 
default values if no preferences file is found when the 
application is launchecL We want our preferences to Ix" 
initialized as soon as the appIic:ition lias finished launching, so 
an appropriate eveni handler to conned is the Will Finish 
Launching event Iiandier in tlie Application Suite, This is 
equivalent to Coc'fxTs awakeFromNib method. It is invoked by the 
.system after the application's nili files have lieen loaded, the 
user inlerrace lias lieen initialized, and other Cocoa initialization 
has taken place. 

The MainMenu.nib file is the main nib Ole for the application, 
and the Fife's Owner of lliat nib file is Ctxoa's NSApfdicalion 
class, so this is where to connect die Will Finish Launching event 
handler In Interface Builder, open MainMenumib, click the File's 
Owner icon in the Instances pane to seled it, and open the 
AppleScript pane of tlie File's Owner Info panel Expand the 
Application group and click to select the checkbox beside tlie 
Will Finish Uiunt:hing event handler. Tlien click to select 
A[)plication.a[)[)lescn[)t at die bottom of llie File's Owmer Info 
panel, and click the Edit Script button. 

When you switch back to Projed Ihiilder, you will find that 
a Will Finish Launching handler has been added to 
Application.applescript. The Application.applescript script was 
supplied by the AppleScript Dorunient-based Application 
leiiiplale wlien we first cFealed the projeet, but it was empty. 
Type to fill in the statements in the new' Will Finish Launching 
handler as shown in Listing 8. 


listing St Applicatk}n*applescript 

C Appljoition.applescript 
CPiVpcrrk:s*) 

property prefsControllerLib ■ null 
C HaiiiMers O 

on 1oadPreferencesControllerLib() 

— Ijoads l^fercno’sControlleriib from PrcfcfmccsQ>imQlle^^ if not loaded 

if class' of prefsControllerLib is not script tketi 

load script POSIX file ^ 

((path for script “PreterencesController" “* 
eKtensioo "sept'') of main bundle) 
set prefsControllerLib to ^ 

pteferencesControllerLlb of result 
end 1 f 

end 1oadPre fe rencesCo Mt rol1e rL±b 
F livtiiL haiidio^ *) 

on will finish launching theObject 

— Initialuteji tht appikniion aftisr main nib fileii am kKidc.^ and initialimJ by Ckx:oiL 

— Connected to Rte's Owner in MainMenii.nib 

— tnihalizc pretwencts to defenJi vahKs, if prettrenco fik ixH foujxl 
ioadPreferencesControllerLib() 

tell prefsControllerLib to initPrafsO 
end will finish launching 

You know from earlier work what chain of events this event 
handler unlciishes. 

Notice, however, that this is the first time we have called a 
metliod in PreferencesController.applescript from outside of that 
stripi., in this ease, from Application.applescript. We therefore 
needed a handler to load the preferencesControllerLib senpt object 
from PreferencesController.applescript into a property in 
Application.applescript. We did this the same way we loaded a 
scripi prtjperty from Preferencesyodel.applescript into 
PreferencesController.applescript, The necessary property and 
handler are shown in Listing 8, 

Until Next TUne 

'Ihis installment is now complete. We have a working 
preferences system for r>oyje. 

To clieck it out, first compile LXjyle for deployment, hi Project 
Builder, oiien the 'raigets pane by clicking the 'faigets tab. In the 
Build Styles area at the btitiom, .select the Deployment radio button, 
tlien reliLiild the application. In tlie Finder, ofxn tlie Build subfolder 
in tlie Doyle piojeit folder, and drag a ropy of the 13oyle application 
into your Applications folder. Double-ciick it to launch Doyle and 
see its main window ofxn. Tlien cluxjse Doyle -> Preferences and 
see the Preferences window open. If tliis is tlie first time you have 
am Doyle, there was no Doyle Prefeiences file in existence, so you 
should see that the biiuon is checked to refied the default value of 
tlie [irefemnce. Unciieck it and close tlie Preferences window. 
Reopen the Preferences window, and you will again see it 
unchecked, proving dial it sucx'essfidly wrote the nenv preference 
value to disk and retrieved it. You am even quit and relaunch Doyle 
and fx^ifomi die test again, if you don’t believe it. 

In the next installment, w^e will write the nece.ssary scripts 
to make the Doyle Usage Log work, and to save and retrieve its 
values in an AppleScript Studio docunient. We will, of course, 
use our new preferences system to determine whether the 
Comments column in the log window should be shown. 
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It's time for you to take a look at MGI 

MG I, a plug-in to 4D's award-winning server, WebSTAR, is 
designed to provide functionality to otherwise static web sites, 
whether for a private intranet or enterprise - class ISP/ASR 
MGI was specifically developed to be used by web graphic 
designers with no scripting or programming experience, if 
you know HTML, you know MGI. And if you are a 
programmer, you can learn MGI by the time your pizza is 
delivered. You can try out MGi for free - right now - without 
obligation by downloading a fully - functioning demo at; 


http://www.pageplanetsoftware.com 
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QUICKTIME 

TOOLKIT 


hy Tim Monroe 


Broadcast News 


Broadcasting Movies Over a Network 


IlVTRODUCnON 

'llTie key new technology iiitrcxliiced in Quickl'iine 4 was 
suppoit for receiving reahrime strenmecl datin That is to say, 
QuickTime-savvy applicaikms like QuickTime Player or our own 
Q'l'Siiell-based sample applications ca!i receive video, audio, and 
other kiiids of data streamed across the Internet. Real-time 
siroaiTiing, unlike die progres^sivc downloading of movie files 
that has Ix-en availal>ie since QuickTime 3, oan handle live data 
and does not require downloading potentially huge files onto 
I he user's computer; this permits QuickTime playback 
a[)f>lications to suf>]X>rt uses such as video-on-demand and 
rehroadcast streaming. 

1lic real-time streaming provided by Quick'llme 4 was a 
client-side technology only; it did not provkle any means to 
serve up, or transmit, the daUi streams. At that time, special 
software was required to create the streams of data that couki lx? 
sent out over a network and then received and phi yeti back by 
QuickTime-savvy applications. As we'll see, the proUicols used 
in tnmsmitting the data from the server to the client confonn to 
i me met Rngineering 'Fask Force (IF'JT) standards, but 
implementing those protocols in a transmitter application 
required intimate knowledge of a handful of IHTF specifications, 
as well as a gfxid bit of programming. 

QuickTime 5 provides a .set of broadcasting fund ions 
that allow us to create transmitter applications. For example, 
we can take the audiovisual data captured by a camcorder 
attaclied to tine conipuicT and hniadcast that data to other 
computers on a network. Together, the transiniLter 
technologies provided by Quicklime 5 and the receiver 
technologies provided by QuickTime 4 give us the complete 
set of tools we need to send audiovisual sire a ms from one 
computer and view them on another. The good news here is 
that we need to know virtually nothing about the applicable 
IETF specificatitins to do ail this; the really good news is that 
the amount of code we need to write to create a broadca.siing 


application is surprisingly small. Indeed, well be able to 
write this application using fewer than a dozen of these new^^ 
broadcasting functions. 

Ill this article, wele going to see how to use these new APIs 
to build a sample application tliat broadcasts live data to other 
cornpuiers. (krt\s ccill this application QTBroadcasL) In a 
previou.s QuickTime 7(K)lkit article (“Captured”, in MacTeeb 
Decemlx^r 2001), we saw how to use the sequence grabber to 
(‘aptiirc sound and video data from devices attached R> our local 
ctjmpulLT; liere well see how to send ca[>lured data to otlier 
coinputers lixated remotely on a network. 

When it starts up, QTBroadcasi automatically opens a 
tmmilor window, shown in Figure 1; this is modeled tm the 
monitor window we created in tlie [irevious article, but now 
contains a button to start and stop ihe hroadca.sting. 



f igure i. 'Ihe monitor window of QTBroadcast 

The Test menu of QTBroadcast is shown in Figure 2; as you 
can see, it contains items that allow the user to select an SDP 
file (which wc'U describe later) and to configure the 
broadcasting settings. 


Tim Monroe \s a memloer of the QuickTime engineering team at Apple. You can coniaci liiiii at iiionroe©apple.com. 
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Test 


Select SDP File... 

3g1 

Configure Settings... 

§§2 


Figure 2 Ti^si menu of i^fBroadcml 


We'll begin by siirveying the various streaming capabilities 
provided by Quicklime, and we'll lake a briel’ look al the 
protocols that underlie those capabilities. Then well consider 
the code we need to add to our basic application shell to allow 
it to broadcast live data streams. Note that Qtiiikl'ime's 
broadcasting APIs are currently available only tm Maeintash 
openiting syslcins (Mac 08 8 and 9, and Mac OS X). 

QoIC:kTiMK SnUiAMiNG 

Slreuming is ihe process vvhereljy one eomiHiter (tlie 
iransmilier) dtops a file or sequence of bytes up into discrete 
chunks (called packets) and sends them atrross a network to 
another cf>mpuier (the ntaiu^er m dimi). The client’s job is to 
reassemble the packets and do the right thing with them. Ihe 
series of packets is a stream. For present purposes, we are 
interested only in streams of aiKliovisual data that can ix^ 
reassembled and played back as a QuickTime movie. 

It's important to keep in mind that QuickTime has 
suppoitcd a kind of streaming, c^dlt^d HITP siTmm\t% or 
pn)gre^sn>e downloading, ever since QuickTime 3 was released 
in 1998. QuickTime’s TlTTl^ streaming allows the QuickTime 
browser plug-in to begin playing a movie embedded in a web 
page before the entire movie lias downloaded to the local 
comtmLcr. HTTP streaming is essentially a file transfer protocol, 
in the sense that the entire movie is downloaded to \\\tt user’,s 
computer. One key advantage of QuickTime’s HTTP streaming 
is that a user can begin interacting witli web-based content 
l3efore the entire movie arrives on the user’s computer. As we 
saw^ in an earlier article^ the movie file embedded on the web 
page is a ,standard QuickTime movie file saved in Past Stan 
format (where the movie atom i.s the firs! atom in the rnovte file). 

Quick'l'ime 4 introduced a different kind of streaming, 
called real-time streaming. With real-time streaming, packets are 
sent out over tlie network in real time (so that, for instance, a 
10-minute movie w^ould take 10 minutes to download). When 
packets are received by the crlicnl application (for instance, by 
QuickTime Player), tliey are reassembled into a QuickTime 
movie and played for the user. In general, packets are discrarded 
as socm as they have been played, so no file is ever created on 
the u.seds local storage devices. 

QuickTime's real-time streaming uses an open TPTF 
streaming protocol knowm as the Realtime I'ransfxjri Protocol 
(RTP) to send the pac:keLs of video and audio data. For control 
information, .such as establishing a connection between the 
client and server or telling the server to jump to a new lime in 
a video-on-demand movie, QuickTime uses a different protocol 
known a,s ihe Realtime Streaming Protocol (RTSP). Figure 3 
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iihows the basic network protocols used by QuickTime’s 
sireainin^^ architecture, RI'SF uses the TCP/LP transport layer, 
while RT!^ uses the lower-level IJDP/TP transport layer. 




I I 

Control 


jrtlQrmation 


V^~ 


Audio 


CIkdt 


Figure jL* Ibe hctsk QuickTinw streaming proiocoh 

Because R'lP uses UDP/IP, it does not guarantee delivery of 
pat’kets. So it's possible for some packets to get lOsSt in transit 
ami never arrive at ilie client cotripiiter. Ihis packet lass can 
result in some degradation of tlie video and sound when the 
movie is played !>ack on the client coni]>uter If you need 
guaranic'ed delivery of packets, you slioukl use I t^Tl P streaming* 
which uses TCP/IP to ensure that all imnsmitied packets are in 
fact received (by retransmitting any lost packets). 

QiiicrkTime supports streaming of video, audio, and text 
data iti any of llie i'ormaLs that can l>e played locally by 
(^uick'riine, including AVI, Sorenson, QDesign, MIM, ami MIDI, 
It onntit cunently stream movies that contain sprite tracks or 
that incorporate features that depend on track references, such 
as QuickTime video effects, chapter lists, and some tweening 
effects, lo handle these sorts of movies, ytju c^m either use 
HUP strcmiing or you can create movies that store some data 
IcKTully and cornltine tltat data with data receivetl via RIP 
streaming. You can even create movies some of whostr tracks are 
deliveretl via HTIV streaming and sotiie via RTl^ streaming. 

The Piles that reside on the stre;miing server are standard 
QuickTime movie files, wiiii one imptaiant addition: each track 
in tile m<wie that is to be streamed acrt>ss the network must Ix! 
accompanied by a hint tmek. 'iTie hint track contains 
infomitition that tells the server software liow to packeti:;^e the 
corresponding streamed truck. In other words, ilie hint track is 
a son of blueprint for crenting stream.s of data. Without the him 
track, tile server software would have to knt>w^ a great deal 
alxuit the patticular audio or video fonxiat conlaineti in the 
sireiimed track, so tliut it woiikl know how best to chof) the data 
up into packets (for instance, po.ssibly duplicating some of the 
packets to protect against losing importani frames of video). 'Hie 
hint track tabulates the server software from having to know 
anything atxna the actual video or audio data it's serving. 

'Ihis is es|x.‘cially imjxjrtam Ixxaiise it allows streaming 
servers to run on operating systems that don’t even run the 
QuickTime client software. Indeed, the first comtnercially 
available QuickTime .server appliotion, Apple’s Quick'l'ime 
Streaming Server (Q'l'SSl, debuted on macliines mnning the Mac 
OS K Server s«3ftware. Moreover, Apple has released die source 


code for the QuickTime Streaming Server under the Apple 
Public Source License, wliich conforms to the Open Source 
community guidelines. Versions of QTSS currendy mn under 
Windows and various flavors of UNIX, including Linux. 

QiickTimf. Broadcasting 

Tlie broadcasting APIs introduced in QuickTime 5 allow us 
to create li roadcasting applications (or, more simply, 
broadcasters). A broadcaster is an application that takes data 
from a source other than a hinted movie, compresses dial daUt 
(if necessary), packetizes that tiara into uStrenms, ancl then sends 
the .streams out over a network. In ihc simplest tuse, the streams 
are targeted at a single specific client on tlie network. This type 
of .serving is called unicasting. It's also possible to target a set of 
streams at more than one dienl on iUa network, using a special 
reserved address; this type of serving Ls called muilkasting. 

The Qoickl'ime broadcasting APIs support both unicasting 
and multicasting. Sotne routers, however, are not configured to 
allow multicast sircaiiLS. In du.s c:;isc, we still need to use a 
streaming server (such as Q'BS). We am transmit the streams to 
a machine running Q'fSS, which then unicasts distinct streams to 
any numlKT of remote clienis. 

’Hie braidcasling APIs can Ik‘ divided into two general 
categories, which well call the .sourcer APIs and the presentation 
APIs. Wc can use the sourcer APIs to select and configure a 
source for llie broadcast data, (A sourcer componenty or sourcer, 
is a component that can read data from a sficcific kind of 
source.) Currently QuickTime supports broadaisting data from 
any of tliese kintLs of .sources: 

• Data ciipmred using a sequence grablx^r coriiponent from 
audiovi.sual devices 

• Movie files .stored kxally on the iransmiiter 

• Precompressed metlia data that is not stored in a [iiovie file 

’Hiis last kind of source allow.s u.s to broadca.si virtually any kind 
of media data; we simjiiy need to jiass die aj>propriate data, a 
sample description for that tlata, and (optifinally) a timestamp 
and duration. Keep in mind, however, diat the tiicni receiving 
the broadcast needs to have a media liandler for tliat kind of 
data. ALSO, some kinds of data (for iastance, sprite media data or 
Plash media data) do not re.spond well to packet loss and hence 
are cuiTentiy not good candklatcs for broadcast .streaming. 

We use the prmmtatkm APIs to present (or liroadcasl) the 
data provided by a .sourcer. A presentatkm is a collection of one 
oi‘ more .streams of data, w iiich am consist of packets of audio, 
video, text, or other data. You migiii think of a presentation as 
the streaming equivalent of a movie and the streams within the 
presentation as the stpeaming efjuivalent of a movie's mteks. The 
diem application receives llie j)re,sentaiion and rtrassembles it 
into a movie, wliich it plays back in exactly the same way it 
plays a kxiil movie, 

Tlie sourcer and presentation AIT.s are a marv'el of 
simplicity. As 1 mentioned earlier, we w ill Ix! able to develop a 
broadcasting application using fewer than a dozen broadcasting 
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funcLujns. In fact, for the inoinent we won't need to use any of 
the sQurcer functions at all, since well rely on Quicklime's 
default behavior of using I lie sequence grabber as the source for 
the broadcast data. So let's get started. 

Setting Up For Broadcasting 

Before we can lx?gin broadcasting live audio and video data 
caj)tured from an audiovisual device attached to our computer, 
we need to initialize our application for broadcasting and then 
create a prcisentarion. As we've seen, a pre.sentation is analogous 
to a movie: it coiLsists of one or more stre^mis of data targeted at 
one or more remote computers. In Q13roadcast, we shall allow 
at most one active presentation at a time, and the data Ixiing 
l7roadt:asi will be displayed in the monitor window (see Figure 
i again), which also contains a button that can be used to start 
and pause the broadcast, lb keep tmek of the presentation and 
the monitor window, well use these global variables: 

QTSPresetitatioa gPres^nia Lion = 

kQTSInva J-ldPresentation: 

QTSMotiflcationUFP gWotifitationUPP - HULL; 

Dialo^Ptr gMonitor “ NULL: 

Us^rTt^mUPP gMonitorUBerltemPtocUPP = HULL: 

Boot pan gBroadcasting = false: 

The gPresentation global variable is an idcniiFicT for the 
single presentation supported by Ql'Broadca.st; as you can see, 
it's of type QTSPfesentation and is initialized to the value 
kQTSInvalidPresentation. Associated with the presentation is a 
presenlalion notification procedure, which we identify using tlie 
gNotificationUPP global variable. Our notification prexedure is 
c'alled on specific events involving the prestmLation, sucli as 
when a presentation is first created and when a connection to 
the client machine occurs. 

We use the gMonitor and gMonitorUserltemProcUPP glol^al 
varialdes to keep mack of die monitor window and the user item 
in that window (where we draw the video data that's being 
broadcast). Finally, we'll use the gBroadcasting global variabie to 
keep track of whether we’re eurrenlly [broadcasting data or not. 

When QTBroadcasl starts up, it C'alls the QTBC_lnft function, 
defined in Listing 1, to create the monitor window and to 
alloc'ate the universal procedure pointers gNotificationUPP and 
gMonitorUserltemProcUPP, 
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We can help clean up ynur act. 


I fur b r oadc asting 


OSErr QTBC_Init tvoid) 

( 

OSErr myErr = noErr: 


QTBC_Init 


// alkx:aie glcrfxil st(jraf*e 

gNot i ficatJ onIJPF = (QTKNotlf irationUPP) 

NewQTSNytift,catiQntIPP(QTHC_NotlflcatlonProc] : 
if (gHqtlficationUPP ~ HULL] I 
myErr “ paramErr: 
goto bail: 

1 


gMon ItorlJfierrteniProcUPP “ NevUserltemlfPP 
(QTBC_t]serI trfniProc:edur0): 
if (gHonitorUserltemProcUPP == NUIX) f 
myErr = parajnKrr: 
goto bail: 
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I 

// open the monitor window 
gKonitor - QTEC_CreateMonitorWindoiir(): 
if (gMonitor = NULL) I 
myErr ^ meHii'allErr; 
goto ball : 


ball: 

// if an error occurred, dean up 
it (aiyErr [“ noErr) 

QTBC.StopC): 

retyrn(inyKrr) j 

] 

QTBC_Init calLs NewQTSNotificationUPP and NewUserltemUPP 
to create the two UPFs, and it calls the application funeticjn 
QTBC_CreateMonitorWindow to eremite and display tlie monitor 
window. Well c:onsider QTBC_CreateMonitorWindow in depth a bit 
later (Listing 9); for the moment, it's suiricient to kor>w that it calls 
GetNewDlalog to create a dialog window from infomiation in the 
appik'ation's resources. 

If any error occurs in QTBCJnit, we don't want to continue. 
In that case, well call the QTBC^Stop funaion, whicii is defined 
in rJsiing 2. QTBC_S1op simply deallocates the two LlPPs created 
l)y QTBC_lnit and disposes of the monitor window. 


listing 2: Shuttk^ down broa dcas tii^ __ 

QTBC_Sfop 

void 0 TBC„Stop (void) 

I 

// dciillocitc any global storage 

if (gWotificationUPP 1- tfULL) ( 

DisposeQTSNotificationUPP t gNotificationUFF): 
fiNotificationUPP = NULL: 

I 

if (gMonitortL^erltemProclIPP [= NUIX) { 

DifipciaeUaerTieinUPP(gMoniLoi:UserItcjnFrot.'UPF) r 
gHonitorUserltGiiiFrocUPP = NULL: 

I 

// dose the nioniior window 

if [gMonitor NULL) 

DisposeDlalog(gMonitCii:) ; 


Wc also call QTBC_Stop just before QTBroaclcast terminates- at 
that time we will also call the QTSC^StopBroadcasting function, 
which calls QTSDisposePresentation to dispose of the 
presentation gPresentation. (QTBC_StopBroadcasting is defined 
later, in Listing 7.) It's imptjrtanl to dispose of the IJFPs and the 
monitor windc^w only after w<^ dis[iose of the presentation itself; 
accordingly, our application-specific shutdown routine, 
QTApp_Stap, contains these two lines of code: 

QTBC_StopBroadcastlng() s 
QTBC_StapO : 
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Creating’ a Presentation 

If QTBC_tnit completes successfully, the monitor window is 
displayed on the screen but it contains no image and the Start 
button is inactive (as shown in Figure 4). 



Figure 4: Ihe monitor window on application launch 

Before we ean begin broadcasting data, we need to create a 
presentation. We do this by calling the QTSNewPresentation 
funcrion, like this; 

myErr = QTSH^wPreseatationtffiyPresParamsPtr. fiigPresentation): 

'fhe second parameter is the address of our global variable 
gPresentation; if QTSNewPresentation completes successfully, it 
returns an identirier for the new presentation in ihai variable. 
The hrst parameter Ls the address ijf a neu^ prestmlalkm 
parameters structure, which is defined like this; 


its dients. 'Ihis file describes tlie types and fonnats of die media to 
be transferred, the tiansport protocols, and the addiesses to which 
the media are to l>e sineamed. Here's a sample SDP file: 

vKi 

c^IN 1P4 224.2.1.2/15/1 
Bi=audio 1000 RTP/AVP 12 
iii=video 2000 RTF/AVF 101 
a^rtpmap: 101 11263-1998 

Tlie line beginning with specifies the protocol version, 
wliich eurrendy is 0. Ttie line beginning with ''c-'' specifies the 
connection infonnation, which consists of a network type and 
address type (here, "'IN IP4'' for IP version 4 addressing on the 
Internet), the desdnatiem address (here, ''224.2.1 which is an 
address reserved for multicasting), a time-to-livc value (here, 
15), and die numl>er of contiguous multicast addresses (here, T). 
The lines beginning with indicate which transport 

protocols and ports to use for specific media tyfx,\s. In the file 
shown above, the audio data is to be sent via RTP to port ltX)0 
and the video data is to be sent via RTP to port 2000. Finally, the 
line beginning with “a=" specifies media allributes. In this case, 
the rtpmap attribute provides information about dynamic 
payload binding. 

In t>ur sain[>le application QTBroadcast, the user selects an 
SDP file using the first menu item in the Test menu (namely, 
''Select SDP File...”). In response to menu item, we call the 
QTBC_SetupPresentation function, which in turn uses our 
Standard framewcjrk function QTFrame_GetOne File With Preview to 
allow the user to select an SDP file. 
QTFrame_GetOne File With Preview returns a file system 
spec:iric:atic)n for that file. We on then fill in the relevant fields 
of llie new presentation paraincLcrs siruciure like this: 


struct QISNewEresentationParams I 


OSType 

const void * 

IJTnt32 

QTSEdilListHanclle 
SlTit32 
TimeScale 
QTSMediaParams * 
QTSNotificfltionUPP 
void * 


di^taType: 
data; 

daiaLength; 

udiLListj 

flags: 

tlsieScaie: 

mediaParams; 

notiflcatiqnProc; 

notlfitationRofCon: 


So before we can call QTSNewPresentation, we need to allcx'ate 
a new presentation parameters staicture and fill in most of its 
fields. We alloc’ate this structure by calling NewPtrCtear: 

nyPresParatii.'^Ptr = (QTSKewFrcscntationParaius *) 

NowP t r C1 ea r {al ze o r (QT SNewP r e aen t a t i onPa raniiJ)) : 


Tlie first diree fields of tlie new prcsenUition p^mimelers 
stRKTure contain information alx)Ut some of die network settings to 
lx used l>y the presentation, suc:h as the tkistination 1? address for 
die brtradatst and tlie [xiils to use for the data streams. Tlie IETF has 
defmed a standard format for tliis infomiation, called the session 
clescrif}tion jmytocol (SDP). An SI>Ffile (that i.s, a file that conforms 
to die SDP) is used by clients and servers for initiating a network 
connection and transfer of multimedia streams lietween a server md 


inyPrGKparamfiPtr->dat3Type " kQTSFi IcPataType: 
rnyPrcsParamsPir >dai:a ijinyPSSpec; 
inyPresParamaPir >t]at3LeiJgtfi == siKSof (luyESSpec); 

Quick'lline also supports SDP information stored in memory (in ' 
which case the cfataType field should be set to 
kQTSSDPDataType). In QTOroadeast, well restrict our attention 
to SDP files only. 

The editList field of the new presentation parameters 
structure is a handle to a QTSEditList structure, which holds 
information about edits for stored streams. For live broadcasting, 
we can ignore that field. 

Tile flags field of die new presenlation parameters structure 
contains information for the presentation we are about to create. 
Currently these flags are defined: 


eniim { 

kQTSAut oMod e Fia g 
kQTS D on tS howS t attisF lag 
kQTSSendMedlaFlag 
kQTSRp-ceivf^Mod laFlag 


“ OxOOOOODOl. 

- OxOOOOOOOS, 

- OxOOOIOOOO, 
“ 0x00020000 


The kQTSAutoModeFlag flag indit:ates that the presentation 
should lie automatically configured to iLs defiiult seLtings; mo.si 
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SECURING THE GLOBAL VILLAGE 


iinix)nantly, tills means lhal the default sourcer is to l>e used, 
which is the sequence grabber 'Ihe kQTSDontShowStatusFlag flag 
indicates that w^e do not want QuickTime to create a streaming 
,sLaius handler for the presentation; if we rccjuesi a ,staius handler, 
it displays connection and status information in the monitor 
window (that is^ in the window associated with the sequence 
gi'al>l)er). For instance, when we first create u presentation, 
QuickTime attempts to connect to the specified target or targets 
and displays the status message shown in Figure 5 



figure 5 : 'Ihe statm message while connecting 


inyPrefiFaran3sPti:->flags = kQTSAutoModeFlag ] 

kOTSDontSbtiwStatusFleig | kQTSSendMftrftaFlag 

The timeScale field of the new presc‘ntation parameters 
stnicture is currently unused (as far as 1 can determine); in 
QTBroadcastj we set that field to 0. 

The mediaParams field holds a pointer to a media 
parameters stmeture, of tyfie QTSMediaParams: 

struct QTSMediaParama I 
QTSVldGoParaitu; y; 

QTSAudioParaitts a; 

I: 

As yoti can see, this stmeture contains a tnrieo Jjarameters 
stnicture and an audio parameters si met u re {of types 
QTSVideoParams and QTSAudioParams respectively); these 
stmetures contain infcirmation about the video and audio media 
data being previewed locally — that is, the data being displayed 
in the monitor window and the sound played through the 
computer's speakers. In Q'rBroadcasc we want lo leave the 
audio settings at their default values, but we want to cxinfigure 
the video sellings so tliat the preview draws in the correct 
location in the monitor window. We l>egin by allocating a ne\\' 
media parameters struaiire; 

myMediaPararasPtr “ (QTSMediaParams *) 

HewPttCleat (siseof (QTSMediaParaais)}; 
myPresParainsPtr->inediaParains = myMediaParamsPtr; 


When the presentation is ready and the recjuisite network 
connections have been established, well see the message shown 
in Figure 6. (Keep in mind that the.se status messages appear on 
the transmitter only; the broadcasting client also displays some 
status information while establishing a connection to liie 
transmitter, which we’ll encounter later) 



I 


Figure 4* Ihe statm message when ready 

The remaining two flags, kQTSSendMediaFlag and 
kQTSReceiveMediaFlag, indicate whether we want to send or 
receive data with the presentation we’re creating. In 
QTBroadcast, we set our flags like this: 


At this point we want to call the QTSlnitializeMediaPanams 
function, which initialises the media parameters stmeture to 
some default values: 


my Er r = QTS Initial d ia P a r ants (itiyMed ia Pa rams P t r); 

Now let’s configure the video previewing, 'the video 
parameters stnicTiire looks like this: 


struct QlSVldeoParama 
Fixed 
Fixed 

HatrixRecord 

CGrafPtr 

GDBandle 

R^nHandle 

short 

RGBColor 


1 

width; 
height: 
matrix: 
gWorld■ 
gdFtandte: 
cl i p; 

graphiesMode; 
opColor: 


Notice (in Figure 1, once again) that the preview images are 
drawn in the usttr item rectangle, which is 176 pixels wide and 
144 pixels higfi and is of! set frtnn the window origin by 10 [pixels 
vertiailly and horizontally, So we’ll use these lines of code to 
place the images in the proper location: 

niyPresParamaPtr->medlaParaata->v.width = Long2Flx(l/&): 
niyPreEParanisPtr‘>niediaParam£->v.helght “ LoTig2Fix(l44): 

Tratia^lateMatrlx(&(myPreHPatamB?tr->in£diaParams->v.matrix), 
Un£2Flx(10). Long2Fix(10)): 


And we’II set the poll and graphics device like this: 

iiiyPresParain3ptr->mediaParaiits->v .gWorld 
GetDialogPcrt (gMctiltor) : 

myPresParamsPtrOmediaParama >v.gdHandlc = NULL; 
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Finally, the notifjcationProc and notificationRefCon fields of 
the new preseniation parameters structure specify the 
notifiration pnx'edure and a reference constant that is passed to 
the notificaik>n pnx:edure, 

nyPreisPa ramflPtr - >dotl ficatlonPtoc “ gKotiflcatlonUPP: 
niyPresParamflFtr->iiotiflcatlonRefCon OL; 


At long last, we are ready to call QTSNewPresentation and 
QTSPresP review; 

njyErr " ClTSNewPresentatioti tjnyPresPsrainsPtr, £igPteHentatlon); 
myErr “ QTSPtesPreviewtgPresentation, kOTSAl1 St reams< NULL, 
kQTSNocmalForvardRflte* 0): 


Listing 3 gives the complete definition for 
QTBC^SetupPresentation. 


Listing 3: Setting up a presentation 

Q’l’BC_SciiipPit*iit*JiUtion 

OSRrr QTBC_SetupPresedtatlon Cvold) 

( 


UTS NewP tescdtd tj onPd rants 

QTSHediaParaDts 

FSSpec 

OSType 

short 

QTFrantc^FllpFllterUPP 

OSKrr 


♦myPresParaasPtr = NULL; 
*niyMcdiaP3raini?Ptr = NULL; 
nyFSSp€c; 

nyTypeListO " fkQTFitoTypGText1; 
myNuinTypes = 1; 
myFileFilterUFP ^ NULL: 
royErr noErr; 


#1£ TARGET_OS_MAG 
rayNuraTypes = D; 
#endif 


// crciiti n nov pit;sent:nk>n psiraratntTs sirutiurc 
myPresParsiitsPTr - {QTSNf'wPresentatioriPararaa *) 

Nowp t r GI oa r (73 i z eof (QTS NewP r an t a 11 on Pa r am e)); 
if (wyPreisParainaPit ^ NULL) I 
niyErr ^ HemErrorO; 
goto bail; 


// nratc a now mo^lia pjranxnm stniourc 
inyHed iaPcirainBPt r ■* (QTSHediaParaniE *) 

NowPt rCl ea r t s 13500 f (QTSHod i a Pa rams)) j 
if CmyHediaParBiiaPtr = NULL) I 
niyErr = NeoiError (): 
goto ball; 


// iniiioJiirr ihc media paranH-^irrs u> duliiult valiirs 

myRrr = QTSTnf t lal iKoNod laParaniB(Ei!yMedisParamEPtr); 

If (myErr t= noErr) 
goto bail: 

// cikit an SDP file fnim the user 
myFileFlltprUPP - QTFraioe_GoiFlleFlltettJPP 
{(ProcPtr3QTFranie .FilterFiles); 
layRrr “ QTFranic_GotOnoFiip.WXthProview(myNUTaTypeE, 

£UTFramoTypoLiatPtr)myTypeLint, &niyFSSpec, 
ntyFileFiiterUPP); 

If (loyErr noErrJ 
goto hail; 

// Man brtiadcaMing Jnim an SDP file 
piyPrcsParamsPtr >dataType = kOTSFileDataType; 
myPresFaramsPlr >data * (iioyFSSpec; 
myPresPflraoBPtr-XdataLenglb sizeof(myFSSpec); 

// set Uic pd^scntatkin Hap: use lHX]ucm:t tinibber, tkxnT displays blm.^ Q movjf , 
// and send data 

inyPreaParajnsPtr->fIagfi ^ kOTSAutoModeFiag [ 

kOTSnantShovStatuaFlag | kcyTSSendHeoiaFlag: 

niyPresParaiisFtr->timeScalo “ 0; 
inyPresParaiiisPtr->iiiediaFara«s ^ tnyModiaParenifiPtr; 


// fill the^^e in to get Matus m^tificaUun^ 

myPresP3rainBPi:r->!iotificatlonPtOc “ gNotifiCationUPP; 
inyPresP3ratiiBPtr->notiflcatlonRefCon " OL: 

// ddine the display sitee and the ddanlt traasmissitm size 
iiyPresParainsFir->a*ediaFaranifJ'>v-width “ Ujng?.Ft z(176); 
myPresParamsPtr'>medlaParams->v-height = Long2Pix(144); 

TranslateMatrix 

£ i (tuy PresPa ratnsPtr - >iBedlaParams' > v .matrix 1, 
Lorig^Flxd O). Long2Fix(10) ): 

// sei die window that Sequence GrabbtT will draw into 
myPresParanisPtr - >mediaParaiES - >v, gWorId * 

GetDialogPort(gMonitor): 

iiiyPresFai:ajii5Ptr->medlaParaiiiS'>V*gdHan[lIe = NULL; 

// create a new presentation 

inyErr = QTSNewProBontatlontrayPresParainRptr, 
igPreseatatlon); 
if (niyErr H noErr) 
goto bail; 

myErr = GTSPresPreviewtgPresentation, kQTSAllStreamK. 
NTHX, kCTTSKoniLal Forward Rate I 03: 


bail: 

if (niyFresFaramsPtr 1= NULL) 

DisposePtrt (FtrlmyPresParanisFtt}: 

if (TnyMediaParamsPtr 1 “ NULL) 

D i s pose Ptr C (Ft r 3 ayHed i aP a r ams Pt r): 

If (inyFileFilterUPP 1= NULL) 

DisposeNavObjectPil terUPP(rayFlleFntorUrP): 

return(myErr); 

] 


Notice ikit we dispose of the new pre.seniation parameters 
strucaiie (myPresParamsRr) and the im^dui |);inifnciCTS slruciure 
(myMediaParamsRr) Ixrfore reluming fitun QTBC^SetupPresenlation. 
QTSNewPresentation Likes aue to copy all the intbrmiition we pass 
it, including any blexrks of memory referenc’ed in tlie new 
]:>[esentarion parameters sinicttine. If w^e had alkxrated any oilier 
inlbrrmlion (for insLince, a clip a^ion), we shixild also dispase oi' 
tiial niemory too. 


BKOADtlA-SllINCi 

Ntjw we've created a pre.sentalion anti requested that the 
video data that ts to lx* hroadcasi be previewed in the monitor 
window. In order for Lite preview'ing and subsequent 
liroailt:asting to i>roceed, we need to grant Quickl’ime some 
time to process the presentation. We do this by calling the 
QTSPresIdte function periodically. As uMiuI, we'll add some 
axle to our application's QTApp^ldle function, which is called 
whenever we receive a null event; 

if (gPresentation 1“ kQTSInvalidPresentation) 
QTSPrGsrdle(gPresfintstion. NULL): 

This just says: if we have an aitive preseniation. gram it some 
processor timer. 

Startlug the Broadcast 

So far, however, no broadcasting is happening. In 
(^TBroadcast, we wail until the user clicks the Start button in the 
monitor window to Ixgin that process. When the user clicks rhat 
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button, Q'rRroadc'iiM oilLs Lijc QTBC_StartBroaclcasling funaion, 
defined in Listing 4. (Later well take a look at the code that 
liandles those button dicks.) 


Listing 4; Starting broadcastitig 

t/l’UC_Startl}rojdGis<ing 

GSEtr QTRC_StartBroadcaetliig (void) 

I 

// stop ihc pirview 

QTSPtesFreviewtgFtefientation, liQ'i'SAllSt.irf^ainia. NlTia,. 
kQTSStoppedRate. OJ: 

retiirti(QTSPrefiPreroHCgPresantationp kQTSAllStreBinSp 0. 

(P! Kfid)kQTSHoriialForwardRate, OL)): 

I 

QTBC^StartBroadcasting first citlls QTSPresPreview with a rate of 
kQTSStoppedRate to stop previewing the data; tlien it aills 
QTSPresPreroll, wliieh readies the media for subsequent 
l>roadcasiing and performs any necessary handshaking lx.aween 
the transmitter (that is, tlie hroado.sting computer) and ilic client 
computer or <*omputers. (As yuuVe |>rol>ably guessed, prerolling 
a prescnuuioii witli QTSPresPreroll is aruilogous to preroUlng a 
movie with PrerollMovie.) 

QTSPresPreroll returns fairly quickly, as .some of its 
operations involve esutl>lishmg network connectioas and hence 
should occur asynclironously. We get informed of the siitress of 
the prerolling in our presentaTion notificati<m pnH’etlure, by 
receiving a nolificalion message of tyix* kQTSPrerollAckNotification. 
Once we receive tiiis acknowledgement, we can then Ix^gin 
actually broadcasting data by calling the QTSPresStart funt lion. 
Listing 5 shows our complete presentaiion noiilicaiion procedure. 


Listing 5: Handling notification messages 

QTBC:_N<wJrK’aiH^nPnH' 

static PASCAL RTN ComponentResult QTBC_NotlticationProc 

(ComponontRcfsiiIt theErr , OSType theNotificationType* 
void •thcMorlflcatlonParaffiS, void *theRefCon) 

i 

ffpragma unused (theHtr, thij^Notlf icationParans. thfiRefCon) 

QTSPresentation ttyPresenLation "" kQTSJnvalidPreseruarion: 

ComponentResuit myErr = noErr: 

switch (theHotiflcationType) I 

cas(? kQTSNrwP rosrntat lonNoti flent 1 on: 

// when wc gtt This notifiembn, the preicnt^hon lus hern OT^icd 
// and sent to ii^ in rhcN^uificationP&nims; 

// if wc ntxdrd it, wr oiuld retrieve i* firdbw}^' 
myPresentatlon = 

{QTSPresentation)theNotificationParains : 
break: 

case? kOTSP rero 11 Ac kWotlficatlon: 

myErr ^ OTSPrcsStart(gPresentarion* kQTSA]iSTreams, 

OL): 

break: 

case kQTSStartAckHotification: 

case kQTSStopAcknotlficatlon; 
break; 

default: 
break; 

I 

return(myKrr); 

1 


As you tan see, we ignore most of the notification messages. We 
handle the kQTSPrerollAckNotification message, to start 
liroadcasting once tlie prerolling is complete. We also handle the 
kQTSNewPresentationNotfflcation message, which is sent 
whenever a new presentation is created; in this case, the 
identifier for the new presentation is passed in the 
theNotificationParams parameter. (We don't actually do anything 
with that identifier; this ccxle is provided lo illustrate how to 
retrieve it if you need it.) 

Finally we're off and ainning. WeVe created a presentation, 
prerolled tt, and (hopefully) received a nohtlcation that the 
prerolling was sut:ces.sful — in wliich case we've called 
QTSPresStart to start broadcasting data. Now it's up to the client 
to start receiving the data we're transmitting. This can happen in 
one of several ways. The c'lisiesi way is to provide the client with 
a copy of the SDP file tliat we used to initiate the broadcasi 
.sesvsion. If the user opens this file with a QuickTime-savvy 
application, then QuickTime's SDP imfk>rier is chilled Lt> convert 
the SDP data into a movie. When the application opens that 
movie, QuickTime connects to the server, requests that it start 
sending it data, and then receives the data into a Itxal buffer; 
w^hile thi.s buffering is happening, the user will see a connection 
slaliis display like tlie one shown in Figure 7. 


3 = Berkeley Broadca.., m § 



Buffering.,.! .83 



Figure 7: A client mtm message 


Tlie user can tlien save the movie into a new file; in this 
case, the new file is a Qukkllme movie File that contains a 
streaming track; the media tfUa for ihts track is jusl the text data 
in tlie original SDP file. Subsequently opening the movie file is 
pretty much identical to opening the SDI^ file. 

C<>ntn>llmg the Broadcast 

So we now see how to start broadcasting from a transmitrer 
and how to receive the broadatst sire;un on a client. If wc want 
to pause the broadcasting, we cun call the 
OTBC^PauseBruadcasling function defined in Listing 6. 'Hus 
function calls QTSPresStop to stop the presentation and then 
QTSPresPrevfew with a rate of kQTSNormalForwardRate to 
resume previewing in the monitor window. 
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Listing 6: Pausing broadcasting 

QTBC_PiiiiscBftt«lcasting 

OSKrr QTBC_PaidseBrDad{iasting {void] 

[ 

OSErr myErr = noErr; 

inyErr = tJTSFresStopCgPresentatlon, 1<QTSAllStteaiaB, OL) j 
if (myErr noErr) 

goto bail; 

// restart the preview 

myErr = QTSPresPrevlev(gFr^sentatioii, kQTSAlIStrsams* KULL< 
kQTSNorinalForwardRata. 0): 

bail: 

return(myErr); 

I 

After pausing a broadcast by calling 

QTBC^PauseBroadcasting, we could laier rcsunie the broadcast 
by calling QTBC_StartBroadcasting once again. If we want to 
Slop broadcasting for gtxxl (perhaps because the application is 
shutting down), we can cal) the QTBC_Stop8roadcasting fund ion 
defined in Listing 1. This function calls QTSPresStop to stop 
hroadcasl ing and then QTSDisposePresentation to dispose of the 
[jresentation. Notice that we also set the global varialile 
gPresentation to kQTS Invalid Presentation, so that QTSPresIdle is 
no longer called in QTAppJdle. 

listing 7: Stopping broad cas ting 

OTRC_StopBrx>adcasting 

OSErr QTBC.StopBroadcasting {void) 
i 

OSErr myErr = tioErr; 

if (gPresentation 1= kOTSTnvalldPrefiGntation) I 

myErr = QTSPresStop{gPtesentation h kQTSAllStreams* OL): 

if {myErr 1= noErr) 

myErr = QTSDisposePrefi£ntation{gPresentatiDri* OL); 
gPresentation ^ kQTSTnvalidPresentation: 

1 

return(myErr); 

I 


Broaik:ast Settings 

Once weVe created a new t^i^^^c'ntation based on an 
existing S]W file, we want to allow the user to view and 
configure the presentation's settings. QTBroadcasr provides the 
^T'lonfigurc Settings...” menu item in its Test menu; when the 
user selects this item and a presentation is underway, 
QTUroadcast displays the Transmission Settings dialog box 
shown in Figure 8. 



Figure S: Ihe Tmmmission Settings dialog box 

This dialog lx>x shows the source, compression algorithm, and 
packetizer nirrently being used for the audio and video streams, 
and also dist^ays the cuiient data rate for each stream. Notice 
tliat there is no way for tlie user to modify any of these settings, 
since the broadcast has already begun. 

If a presentation is not underway, then when the user 
selects the “Configure Settings.*." menu item, Q'iBroadcasi 
displays the Transmission Settings dialog box shown in 
Figure 9 



Figure 9- ^Ihe Transmission Settings dialog box (modifiable) 

As you can sec, the dialog Ixjx now contains some buttons that 
allow the user to modify various broadcast settings. For instance, 
if the user clicks the “Source..." button associated with the video 
stream, the dialog box shtwn in Figure 10 appears* 
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Without this piece, 
you’re not done. 

Its not enough just to write solid code anymore. Users expect 
an easy-to-use installer when they buy your software. 

InstallerMaker gives you all the tools you need to install, 
uninstall, resource-compress or update your software in one 
complete, easy-to-use package. 

Add marketing muscle to your installers by customizing your 
electronic registration form to include surveys and special 
offers. Even create demowarc in minutes. 

Visit http://www.stuffit.com/installermaker/ to also 
learn about creating Mac® OS X compatible installers with 
InstallerMaker. 

re done. 

The complete installation and distribution solution™ 




Get your beta testing started faster. 


Guarantee your builds arrive safe and 
sound! New Stufiflt 
Express™automates file compression 
and transfer tasks to eliminate costly 
errors every time you exchange data. By 
creating custom drop box applications, 
you and those you communicate with 
can accomplish complex file transfer 
tasks with a simple drag and drop. 
Choose from up to 26 file transfer steps 
with no coding required. Boost 


productivity and save time by 
distributing your custom Express boxes 
to everyone on your list. 


http://www.sttiflSt.coni/express/enteipiisemac. 
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Figure 10: V}e video stream Sourcer Settings dialog box 

Aiicl if the user clicks the “Packetizer...” button associated with 
the video stream, tlie dialog hc^x shown in Figure 11 appears. 



Figure 11: Ihe video stream Packetizer dialog box 

It’s actually quite simple to display all these dialog boxes; 
indeed, we need to call only a single function, 
QTSPresSettingsDialog, as shown in Listing B (which lists the code 
we execute in response to the "Configure SeUings...” menu item). 

Lbting 8: Handling the “Configure Settings.*.” menu item 

QTApp_l lajidkMemi 

case IDM_GKT_SETriNGS: 

if CgPresentation != kQTSInvalidPirEsentation) 
layErr = QTSPreESettingsDialog(gPresentation. 
kQTSAllStrearos, 0, NUIX/ OL); 

if (rayErr !“ noErc) 

QTFcanie_Beep(): 
niylsHandled = true: 
break: 


Monitor Window Control 

WeVe just about finished learning how to use Quickl ime to 
broadcast data across a netwt>rk:. WeVe worked with all the 
basic functions we need to use to create and preroll 
presentations, start and stop previewing, and actually start 
sending streams of data uy a remote client. Let's finish off quiekly 
by taking a look at the code we use to aeate and manage the 
monitor window. 

We create a single monitor window^ at application launch 
time by calling tlic QTBC_CreateMonitorWindow function, doftned 
in Listing 9^ 'I’his function calls GetNewDialog to open a dialog 
box whose attributes and items are defined by a ‘DLOG' resource 
of ID kMonitorDLOGID. 

Listing 9i Creating the monitor win dow_ 

QTBC.CrcatcMonit orWindow 

BialogPti: QTBC_CreateHoriitorWindciw (void) 

I 

DialogPtrmyDialog = NULL; 

myDialog " GetNewDi3lo^(kMf)nltorDL0GID, NULL. 

(WlndowPtt) IL): 

if (myDialog != NULL) I 
short tnyltemKind; 

Handle iiiylteniHandle = NULL; 

Rect mytteniRect: 

MacSetPort[GetDlalogPort(myDialog)); 

// set the user item drawing procedure 

GetDialogItem(myDialog. kHoaltorUserltemlD* &mylteiiiKind, 
^rayltemHandle* imyltemRect): 

SEtDialogltem(myDialog, kKonltorUserltanilD, myltemKind, 
(fTa[idlE)gHonltorUserTteTnProcUFP. &myTteniRect): 

HacShowWin<iow{GetDialogWindow(tnyDialog)): 
QTDC_UserIteiiiProcedure(iiiyDiait>g* kMonitorUserltemID): 

I 

return(myDialog); 

1 

QTBC^CreateMonitorWindow also sets the user item procedure 
for the user item in the monitor window to be the function 
QTBC_UserIt 0 mPfocedure, defined in Listing 10. This user item 
procedure draws a frame around the u.ser item and also sets the 
state of the Start/Pause button; if no presentation is active, we want 
tt> disable the button so that it cannot he pressed. 

listing 10: Drawing the user item in the monitor window 

O' riC_UserlteniFrQCediiK: 

PASCAL_RTN void QTBC_UserItEniProeedure ( 

DialogPtr theDialog, short theltem) 

I 

short mylteniKind: 

Handle myltemHaiidlG “ NULL: 

Rect myltemKectr 

G r af Pt r niy Sa ve d Port; 

OSErr myErr = noErr: 

GetPort (^imySavadPort) t 

KacSetPort(GetEialogPort(theBialogJ): 

if (tholteiD != kMonltorUaerltemiD) 
goto bail: 

// draw a frame around the user item rectaneJe 

GetDialogrteE(theDialog. kMonltorUserTterolD. ^yltamKind* 
^oiylteraHandle, ^mylteinRact) ; 

InsetRect (&myIteiiiRect, 1, 1) \ 

Ka cF tame Rec t (&my 11 emRe c t): 
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// enable Ihc SUflAlop iHjUan in the moniLor window 
GetDialogIteniltbeBiaiog, kMonitorButtonID* imyltemKind» 
&myIteo^andlei ^myltamRact): 
if (myTteiiiHandle 1“ NULL) [ 

if (gPresentatlon ” kQTSTnvalidPresentation) 
HlliteControiC (CoDttomandle) 0 iylteiiiIiandle, 255) j 
else 

HiiiteControl ({ControlHandlejniyltemliandle. 0): 

\ 


OSX Carbon 
Mac OS 7.1-9.x 
Windows 95-2000 



ball; 

MacSetPort(mySavedPort); 

) 


We handle clicks on the button in the 
QTBC_HandleMonrtorWinclowEvents thnetion (Listing 11), which is 
chilled by QTApp_HandlfiEvent for any events targeted at a dialog 

[)OX. 


Listing 11: Handling eve nts in the mon itor window 

QTBC_HandicMoni:orWinck>wEvcm*> 

void QTBC_HandiaMon11 o rWiodowEvent s 

(DiaiogPtr theDiaiog> Dialogitamindex thaltamHii) 
t 

short ntyltenaKlnd; 

Bandtc (nyTtoroHandle * Hin*L: 

Rect myttOniRcct; 

if ({theUialog — gHonltor) 

(thelteaBit kMonitorButtonID]) I 

GetMalogTteni(theMalog. kMonitorButtonID, imyltemKind, 

AmyT t rnnHa nd1o♦ &my T temRoc t); 
if CgBroadcasting) \ 

QTBC_PausGBroadcaHtliig(): 

Se t Gon t r o iTi t le ((Gont r o iitand 1 e} my 11 emlland 1 e, 

■'\pStart''): 

I else \ 

QTBC StartBroadcaatingO; 

SetControlTit1«((Gont rolHand1e)myTtemHand]a, 

■*\pFaufle "); 

} 

gBroadcasting “ IgBroadcasting: 

I 

I 


CONCIJLISION 

The broadcasting support included in QuickTime 5 allows 
as to write applications that transmit data captured or stored on 
a local server to a client (or set of clients) located remotely on a 
network* It's importanl to rememi>er that the streams of media 
daUi transmitted by QuickTime’s broadcasting components 
conform to the IL'l'i' protocols (principally, RTF and FI'S?) and 
hence on be received by any stanclard.-^a^mpliani. clieni 
application. As we've seen, QuickTime 4 provided support for 
receiving those kinds of streams, so we can use QuickTime AFls 
to develop lx)ih the transmitter and the receiver. 

Credits 

'thanks are due to Kevin Marks for reviewing this article 
and providing some comments, and lo Anne Jones for 
providing some helpful background information* 
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PROGRAMMER'S 

CHALLENGE 


by Bob Boonstra, Westford, MA 


Megaminx 

Some months the Challenge ideas come easily. Other 
months interesting idea eludes me. This is one of those 
“other" months. The column deadline looms near, becomes 
imminent, encroaches into the present, overtakes me, and 
rushes onward, leaving me in its past. The wrath of my editor 
awaits. What to do? 

Just in time, my collection of mechanical puzzles 
beckons, and an Idea pops into my head. Time for another 
MefferL puzzle, perhaps. SotneLliing more difficuli than the 
Tetraminx Challenge from June of 1999. Something even 
more difficult than the R’biks Cube Challenge. Yes, this 
month well Challenge readers to solve the Megaminx, 
pictured below. 



The Megaminx is a regular solid with twelve faces, 
where each face is divided into one center face element 
(which 111 call a facelet), five corner facelets, and five edge 
facelets. The faces are colored with six ct>lors, pairs of 
opposing faces being colored the same. The solid is divided 
into slices ctirresponding to the faces of the Megaminx. Each 
face can be rotated clockwise {)f coimitTcksckwise, with five 
rotation steps in the same direction bringing the 
corresponding slice back to its original position. Your 
Challenge is to restore a .scrambled Megaminx to its original 
position. Entries this month will t)e complete a|)piicaL!ons, so 
there is no prototype for the code you should write. 

To describe the coloring of the solid, weVe going to have 
to agree on some notation to identify the faceleis. Well 
number the faces from 1..12, thinking of face 1 as the "top” 
face. Face 2 will be one of the five faces adjacent to die top 
face, and faces 3..6 ilie other faces adjacent lo the top face, 
proceeding clockwise from face 2 when viewed from above 
the top face. Faces 7..12 will be numbered such that face N+6 
is opposite face N. We'll number the colors of the solved 
Megaminx using 1..6 as well, assigning color N to the center 
facelet of faces N and N+6. bounds complicated perhaps, but 
if you read carefully, it .should become clear. If it isn't, 
perhaps the following list of face adjacencies will help: 


Fare I is adjarenL io faces: 

2 

3 

4 

5 

6 

Face 2 is adjacent to faces: 

6 

10 

11 

3 

1 

Face 3 is adjarem to faces: 

2 

n 

12 

4 

1 

Face 4 is adjacent to faces: 

3 

12 

8 

5 

1 

Face 5 is adjacent to faces: 

4 

8 

9 

6 

1 

Face 6 is adjacent to faces: 

5 

9 

10 

2 

1 

Face 7 is adjacent to faces; 

H 

9 

10 

11 

12 

Fare B is adjacent to faces ; 

12 

4 

5 

9 

7 

Face 9 is adjacent to feces: 

8 

5 

6 

10 

7 

Face K1 is adjacent to faces: 

9 

6 

2 

n 

7 

Face 11 is adjacent to faces: 

10 

2 

3 

12 

7 

Face 12 is adjacent to faces: 

11 

3 

4 

8 

7 


Your program must process muitipic test cases, the numl)cr 
of which is provided in the file input,txt. Hie initial 
conditions for each test case are provided in file 
megaminxlJN.in, where NN ranges from 1 to the number of 
test cases. Each input file contains 120 lines, 60 describing the 
coloring of the corner facelets, followed by 60 describing the 
troloring of the edge facelets. The lines describing the corner 
faceleLs will cc:)ntain four comma-delimited numlx:rs: Lhe number 
of the face on which the facelet lies, the number of one of the 
other fac'es on this corner piece, the number of the third face on 
tills corner piece, and the c:olor of the fac:eiet. The lines 
describing the edge facelets will contain three comma-delimited 
numbers: the number of the face on which the facelet lies, the 
number of the other face defining this corner piece, and the color 
of the facelet. So, for a Megaminx in the “s<ilvcd'' orientation, the 
rnegaminxNN. in file would contain the following lines for the 
top face: 

1 . , 1 

1 . 4 . 5*1 

1*5,6,! 

1 . 6 . 2.1 

T*Z,! 

1*3,1 

L.4,1 

1 * 3*1 

1 . 6*1 


The puzzle is solved with a seciuence of slice rotations, 
resulting in each facelet being moved to the face that matches its 
color. Each rotation moves the corner and edge pieces of the 
rotated slic^ to new positions. A ckxrkwise rotation of the slice 
corresponding to face 1, for example, moves comer piece (1,2,3) 
to Cl,3i4), which moves to (1,4,5), which moves to (1,5,6), which 
moves to (1,6,2). A cloc'kwise rotation of slice 2 moves the 
comers from (2,3,1) -> (2,1,6) -> (2,6,10) -> (2,10,11) -> (2,11,3) 
-> (2,3,1). 
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— Joe Zobkiw, author of A Fragment of Your Imtigination 

“Resorcerer will pay for itself many times over in .saved time and effort." 

- MacUser review 


“The template that disassembles PICTs is awesome!" 
— Bill Steinberg, author of Pyro! and PBTools 

“Resorcerer proved indispensible in its own creation!" 
-Doug McKenna, author of Resorcerer 
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Includes: Electronic documentation 
60“day Money-Back Guarantee 
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Extras (call, fax, or email us): 
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• Ships with PowerPC native, fat, and 68K versions 


New 

in 

2 . 0 ; 


Fully supported; iPs easier, faster, and more productive than ResEdit 
Safer memory-based, not disk-file-based, design and operation 
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Compares resource files, and even edits your data forks as well 
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All graphic editors support screen-copying or partial screen-copying 
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After reading the input for each test ca.se, you should 
determine the sequence of rotations needed to solve the 
puzzle and output them to a file rotationsNN.tJst. Each 
roiatiun should produce one line of output of the form: 

fscc,dircctloti 

where face is the number of the slice being rotated, 
and “direction" is the character for a clockwise rotation 
and for a counterclockwise rotation. 

Finally, your program should produce a megaminx- log 
file, with one line per test case containing the integer 
number of microseconds used by your application to solve 
thal test case^ including the time to read the input, find the 
solution, and produce the rotationsNN, txt output. 

Scoring will be based on minimizing execution time. You 
can earn a reduction of up to 25% of your execution lime if 
your application has an option to display the Megaminx as it 
is being solved. (Scoring will be done with the display option 
disabled, so the display time will not count againsi your 
solution.) The bonus will be awarded based on a subjective 
evaluation of die tiuality and attractiveness of your 
application. 

This will be a native PowerPC Challenge, using the 
development environment of your choice, provided I have or 
can obtain a copy - email progchallenge^mactechxom to 
check before you start. You can develop for Mac OS 9 or Mac 
OS X. Ytnir solution should be a complete Macintosh 
application, and your submission should provide everything 
needed to build your application. 

Winner of the Decemrer, 2001 Challenge 

Congratulations to Ernst Munter (Kanata, ON, Canada) 
for winning the December Parent-TeachcT Conferences 
Challenge. This problem required contestants to schedule 
appoiiuments between parents of ehildren with their 
teachers. Penalty points were assessed for each retfuesied 
eonference that wa.s not scheduled, for any scheduling gaps 
that caused parents or teachers to be idle between 
scheduled conferences, as well as for elapsed execution 
time. Parents indicate the strength of their desire for a 
conference with a teacher of a given child, and the penally 
for not scheduling a conference is proportional to ihe 
parents' desire to hold one. 

Ern.si starts with an initial assignment of conferences thal 
gives priority first to tho.se parents whose availability is low, 
and then to those conferences that are most strongly desired 
by parents. He then tries to reduce scheduling gaps by 
moving conferences to different slots where both parent and 
teacher are available, assigning die conference to the other 
parent of the child, or swapping time slots with another 
parent who has a conference with the same teacher. I'he 


solution iterates on these techniques until no further 
advantage is obtained, after which it attempts to reduce 
penalties for scheduling gaps by canceling conferences 
entirely. Ernst not only achieved die lowest number of 
penalty points, but did so using the least execution time. 

Alan Sienger again shares the prize with Ernst as the 
best-placing entrant wiihimt a recent victory. Alan’s entry 
incurred about 9% more penalty points, in pan because of 
two factors. First, he did not recognize cases when one 
parent had requested a conference for multiple children with 
the same teacher, correctly observing that this was unlikely to 
happen often in the real world. Second, he did nothing 
special to reduce penalties due lo scheduling gaps, beyond 
scheduling conferences starting from the middle of the 
available periods and working outward from there, 

Tom Saxton took second place {but as a recent winner 
does not share in the prize). Tom also processes conference 
requests in order of ihe strength of the parents' desire to 
hold it, moving other conferences held by a teacher if 
necessary and possible, or rescheduling the parent's 
conferences. Tom's approach incurred about 6% more 
penally points than Ernst's. 

Aeknowledgemenis also to Ken Slezak and Tetuya Takeo 
for submitting solutions in mm-Metrowerks development 
environmeni.s* Ken for u.sing KEALBa.sic, and Tetuya for using 
Objective C, 

Tiie table below lists, for eat:h of the soluLions submirted, 
the number of penalty points assessed due Lo missed 
conferences and scheduling gaps, the total execution time in 
milliseconds, and the penalty points after adding 10% for 
each second of execution time per lest case. It also lists the 
programming language of each entry. As usual, the number 
in parentheses after the entrant's name is the total number of 
Challenge poinis earned in all Challenges prior to this one. 


Name 

Penalty 

Time 

(msec) 

Points 

language 

Ernst Munter (800> 

48515 

571.4 

48B25.0 

C++ 

Tom Saxton (193) 

51476 

760.0 

51997.1 

C++ (OS X) 

Alan Stenger (7S) 

52744 

1482.8 

53636.5 

C++ 

Tetuya Takeo 

54224 

8539.3 

60256.7 

Objective C 

Jan .Schotsinan (14) 

59745 

2192.0 

61364.1 

C 

Ken Slczak (26) 

60646 

smo 

66946.7 

KEAIBasic 


Top Ojntestani's ... 

Listed here arc* the Top Conieslants for the Programmer’s 
Challenge, including everyone who has accumulated 20 or more 
points dunng the past two years. I’he numl>ers below include 
poinLs awarded over the 24 most recent contests, including 
points earned by tliis montlVs entrants. 
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A New System Has Arrived. 



No Mac is complete without Timbuktu Pro, 
the premier remote control and file transfer 
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No network is complete without the smart 
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Timbuktu Pro* netopia. 






Rank 

Name 

Points 

Wins 

Total 



(24 moj 

( 24 mo) 

Points 

1, 

Munter, Ern.st 

265 

10 

822 

2. 

Rfeken, Wdleke 

73 

3 

134 

3. 

Wihiboig, Claes 

49 

2 

49 

4, 

Saxton, Tom 

45 

1 

203 

5^ 

Ta}3f>r, Jonathan 

39 

1 

63 

7, 

Maurer, Sebastian 

31 

1 

106 

9, 

Mallenjrff 

20 

1 

114 

10. 

Cooper, Tony 

20 

1 

20 

11. 

Truskier, Peter 

20 

1 

20 


AND THE Top CON’IESTANT^ LOOKING lOR A RECENT WiN 
In order Lo give some recognition to other participants in 
the Challenge, we also list the high scores for contestants who 
have accumulated points without taking first place in a 
Challenge during the past two years. Listed here are all of those 
contestants who liave accumulated 6 or more ^x^ints during the 
past two years. 


Ranh 

Name 

Pdinis (24 mo) 

ToCal Points 

6. 

Boring, Handy 

32 

144 

a. 

Sadeisky, Cifegoty 

22 

24 

12. 

Shearer, R<yb 

19 

62 

13. 

Sienger, Allen 

17 

82 

14. 

Schotsman, Jan 

16 

16 

15. 

Hepsund, Ronald 

10 

57 

16. 

Han, Alan 

10 

35 

17. 

Day, Mark 

10 

30 

18. 

Downs, Andrew 

10 

12 

19. 

Dcsch, Noah 

10 

10 

211. 

Eaxekas,^ Miklos 

10 

10 

21, 

Flowers, Sue 

10 

10 

22. 

Icshner, Will 

7 

7 

23. 

Miller, Mike 

7 

7 


'There are three ways to earn points: ( V) scoring in the top 
5 of any Challenge^ (2) Ix^ing the first person to find a hug in a 
published winning solution or, (3) i:ieing the first |>erson to 
suggest a Challenge rliat 1 use. Ihe points you can win are: 


1st place 

20 points 

2nd place 

10 points 

3rd place 

7 points 

4Lh place 

4 jxjiiiLs 

5tii place 

2 points 

finding bug 

2 points 

suggesting Cliallenge 2 poinus 


Here is Ernst's winning Parent^l’eacher Conferences 
solution: 


PT-Mainxpp 

Copyright © 2001 

Ernst Mimter^ Kanata ON, Canada 

r 

The task 

Schedule paicin-tcachcf ccnfefcnccs, while oiaxiimzing parent and teacher 
saiislaciion. Each conference relaiing lo a child involves a teacJier^a parent and a 
priority. Satisihetion b masimiSM:d by acccjmmodaUiig those conlerences havii^ lUgher 
priorit)^' while minimizing the time any teacher or patent have to wail between 
conferefices.The input Ls provided in the form of three text files ftjr each test case. 

The output is a test file listing the conferences, and a log file reporting the run times. 

Solulion 

Each input file is scanned to generate an array of conrtsponding records of children, 
parents, and teadieoi. Names are replaced by pointers linking partnis lo cMldreo, 
and parents and teachers to conference requests. Spou-ses are linked to each other. 

Conference requests for diildren with the same parents and teacher reference, are 
combined, their priorities added together and transferred to a single request. AlJ 
redundant requests are then removed. 

Ckynference requests are llrsi styrted to pbee die highest priority requests at the front. 
Tlie first N requests are then sorted to favour requests for conferences with parents 
who Itave less time available. N is the number of tcaibers multiplied by the number 
of available conference periods, 

A processing sequence of the conference iJcritKls is prepared, based on the total 
availability of parents fiyr each peritKi, Periods with less availablliiy will be used first 
in trying to acetymmtKlaLe a requesL 

Then aE requests arc scquenTially servetl.and if possible atrommodated by biioking a 
conference period with the requested tejiclier. 

When no more matches can bt found, a loop of simple strategies is used to reduce dye 
waiting penalties, essentially by shifting ciynfe'rences ;irxyund among lime slots, parents 
and their spouses, and between parents having conferences wltli die same teacher. 

When no more improvement can be made, the set of conferences Ls sent to the disk 
file. 

Version 2 addition: a ^ih waii-reduciion ledinique is added by which conferences may 
be cancelled if the waiting times eliminated exceed the priority points lost 

Version 3 addition: Exploits the rule tliat a spouse may use a parent in the same 
conference, to reduce a spouse's waiting time. In the test cases, this change resulted 
in only a liny improvement. The data structure docs not allow the recognition of more 
than one spouse, so there may still lye some missed oppominiUcs for points savings. 

Limitations 


Where there are twty parents to a child, they are usually “married’’ and enyss linked in 
the database. However, no parent can have more than orye spiyasc, and only one 
crossJinkage can exist. This implies that we can use spousal cross links to find 
idlemaies for conferences, but we cannot infer from the absence of a crosslink that 
(another) spouse does not exist. 

No multiple conferences can occur with the same icadier at die same lime, Le. only 
one parent can be present at a con ferenee.Tliis restriction was removed in version 3. 

Assumptions 

The numJyer of periods tkses noi exceed 251 lliis limit can be incR'ased in the 
FTcompilc-constanis header fdc- 

Clt might have been nice to u.se 32-hit hit maps in liome cases, but 1 thought 32 might 
be a bit too low as a realistic limit ft>r the general c.ase) 

Associated I^gimn Fdcs 


llic main pn^am (diis llle) is“ET-Main.cp". 

Ilie header file “'PT-Files.h*contains classes for the various input and output fdes. 

The header file‘’FT-Rcrsons.h* contains classes fer the person records. 

Ibe header file‘’PT-conipilc^onstants.h'’contains a few compile policies, such as 
the maximum number of periods (defaulting to 255), jwd tJic debug and assert 
ctynmyls. It aLso contains a directory string which can be used to locate the input and 
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LOOKING GO 




Install My Insanely Creat Application for Mac OS X 


Choose Product Features 


Install Features foe Desktop Users 
The md^( tomtmin ippllutlqji will be ThH 

aptdcHi reeDmme nded Tar nrait qvpfj. will be inMaUrd |p 
the Dddi. t’owei UilOI de^ktQ|]' ukcji and iUac uieri wlF> bc 
vecy bappvwlth ihb oipHq^i, 


IntroducHon 
License Agreement 
Enter Password 
Choose Install Folder 


Install Features for Users On Hie Go 

fill* is ih« fccommendcd option tof uisn on Ibt sio, Pow^raoqit 

and iBool^ u:»cf» win be fbo envy of ihelr cowofkers. 

Ail yow Mac aie belong la u». 


Install Selected Components 

^1 lore what youw«nl toimUHr Think dirrcrffnt. Chooin lhi» 
option and pkk iht Individual cotnponiMtli to Instan. 


Previous ^ f Install ^ 


Install My Insanely Great Application for Mac OS X 


Looking good on Mac OS X is easy with InstallAnywheref 


Let's face it, fifsl impfessions are lasting ones. You don't build 
beauttful applicatbits for Mac OS X only to deliver them with 
yesterday's tired installers. 

Zero G has created a poweiful and intuitive installation and 
configuration soliition that is true to today’s Aqua look and fael. 

InstalEA^here has compiete support for Mac OS X, such as 
authenticatioo, file permissions, and platform sj^ific locations 
including installing icons into the Dock, making it the only 
installeryau'fl ever need. 


And when you re ready to deploy to Mac OS Ciassic, Linux^ Solaris, 
AtX, HP-UX, or even <gasp?> Windows, InstaltAnywhere is ready 
too ’ anytime, anywhere, on any platform, 

Sottware innovators like Adobe, Apple, GEA, Borland, HP, i2, Iona, 
Son, TIBCD and XerosL already depend on I nsta If Anywhere for their 
software deployment needs. 

See for yourself why InstaiEAnywhere, the world's leading multi¬ 
platform deployment solutiofi, is also the best looking and most 
powerful instatler for Mac OS X. 




InstallAnywhere 


Download a free trial version from http;//www,ZefDGxoni/gDta/mac 0 SX 


© /M G Sfllhwre, liK. InstiMVviiwtare anil 2 «i C ir indeiiiuia cr RfidBed imltfiiuiLi qI Zcm C SiftwiB, Ik. Mbc h 4 trWmiiili if Apblv OomiwtF, kit, o^bbA In iht U.t 

end -ntruv aiHlfis. He '-BhM 'hr Mac OS K"' ErapliB n i liiiniiHt, of Apple Conpiite Ibl. used wdci feeiiK, All pihpf UnhniwiU vv d Uiii ntmrs. 



ZERO G 


BArferMxOSX 




















output tiU^ in a cUnc'ctory other than the cxecimible, 


PopulateConf&reneesC )i 


'Ihc Iteatkr file Ti‘UtiJilicsh'and the file “n'Utiliiic$,epp“ contain some minor 
utility funoionii, nut all of wltkh may actually be still in use in this version 

The header file ^MyTlmeeh*' contains a micrnsEcmKl timer class. 

V 

ifinclude “PT-Fersons,h" 
jfinclude “PT'Fliea*h" 

Jinclude "FT*compile-constants.h* 
jinelude "FT-tJtilities.h” 
jflnefude “MyTitter.h'’ 

class AvallabilltylyPertod 

// Used in comptiling the optimal period assignment order 

\ 

long availability Sum; // of nl parents 
long periods 
public; 

void !nit(long x) (avallabllitySum=0;perioci=3t; J 
void Tncfemcnr () taveilabil itySmrH-j 1 
longPoriodC) const iretutn period;! 
int operator ■ (Availability By Period^ r) consit 
I return availabilitySum-r.availabilitySum: I 
I; 

class TestCase 

// Omtains the icsoniices of a test case, files, panents, teadicns etc. 

I 

SchedulesPile sehedule&PllB: 

ChiidretiFile childrenFile: 

TeachersFile teacbersFile; 

OutputFile outputFile s 

long nuroPer [ad k; 

Parent* parentj^s 
long numParents; 

Child* children; 
long numChildren; 

Request* requests; 
long numReques ts: 

Teacher* teachers; 
long numTeachers; 

Con ference* conferpnees; 
long nuaiConferences: 

Feriod^t* assigmientOrder; 
public: 

TestCaseClong testNuaiber) : 

// Clonsiruttur jeads all input files and sets up the resources. 

schedulesFlle(testKunber,numPeriods,parents,numParents). 

childrenFl leCtestMumber, chdldrEn. ntiiaChlldren), 

t eachersFi1e(testKumbe r * requests * numRnquest a)* 

outputFlleClestNumber), 

teachers(D), 

numTeachers(0), 

conferences(0), 

numConfetencGfl(0). 

aBslgiiinentOrder(O) 

n 

“TestCaseO 

( 

delete IJ conferences; 
delete [j teachers: 
delete |] assignmentOrder: 

I 

void RunO 

I 

tiekeAssignmeutOrderO : 

LlnkFerentsUithChildrenO ; 

SetupTeachersO: 

ConblneRequestsO; 
numRequests 

NumAbsorbedRaquestS(J: 

AllocateConfereEicesO ; 


Reduce¥ajts(); 

SeadConferencesd: 

I 

private: 

void MakeAsslgnmentOrdarO 

// (lenenites a perkKl order, horn the least availaftle to tlie most available, 

// based on parent avaibblity. Less available perifxbt will be jt^signed first 
I 

#i£ haxhumperiods > ass 

AvailabilityByPeriod* ABP: 
try I 

ABP=nev AvaiiabilltyEyPariod U+ntimPatiodsI: 

I catch (...) I 

Error (^Could not allocate storage for‘'*’'ABP''); 

1 

l^else 

AvailabilityByPeriod ABP[2S6]: 

#endi!: 

for (int period=0;periodC=nujaFerlods:period++) 
ABPlperiodJ .Init(period); 

for (Parent* P=parents:P<parents+nuiDparents;P++) 

( 

long firstPeriod=P->FirstPeriod{); 
aasertCfirsrPeriod>0); 

long lastPerlod=P'>LastpGriod(): 

assert (lastPerlodf=DiiiiiPeriods): 
for (long 

peiriod=f irstPeriod; period <**lastPer lod: perlod++) 

[ 

ABP tperiodj, Increment (); 

I 

I 

qEort(ABP+l.numPerlods.slzeof (AvailabilityByPeriod), 
Gmp<Availahl1ityByPorlod>); 

try [ 

asslgnmentOrder^new Period_t [l+nuoiPerlodsJ; 

1 catcb(..J t 

Error(“Could not allocate storage 
for“.“assignmentOrder”): 


for (int period=0:period<"numPeriods;period^) 
assignjaentOrder (periodJ^ABPlperiod].Period{): 

#if KAXNUMPERIQCS > 255 
delete [] ABP; 
flendif 
1 

void LinkParentsWithChlldrenO 
// Replaces p'dn-■nl^amt■ ami cbildNamc with paRiit and child peanters. 

f 

Child* C=childreri; 

for (long t“0:i<numCblldren; i H XN ) 

( 

Parent* patent l^Find Pa rent (G ^Parent ] Namo ()): 
Parent* parerjt2"FindParetTt(C >Pareut2Naj!ien ): 

C">RegisterParentfi (parent 1 *parGnt2); 

I 

for (long l={);l<nujBChildren;l+i) 

I 

children ti] .HarryParentsO ; 

1 

I 

void SetupTeachereO 

// Scans the already sorted requests (by teacher's name, from teachers file) to: 
// discover unique teacher names, and setup in the leathers array, 

// replaces childNamc with child (assu mes ch ildren File exists). 

// installs avadablity In parents (assumes parrms m. linked to diildieti) 
//Then scans the requests again to make the teachers array 
( 

char * laetTsacherName""": 
char* teachErHaiiieO: 
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My files are 
important. 

Very important 



THIRSBY 

Software 


print 

'the f ile.^re 



I only share my 
files with those 
I trust. 

I trust DAVE. 


Mac to PC, PC to Mac. Cross-platform 
file and print sharing is too vital 
to your business to risk. Trust 
Thursby, the company with 15 years 
experience. Trust DAVE, the solution 
with a proven track record. Share 
files and printers across a network 
with no barriers. DAVE installs on 
your Mac with no additional software 
required for the PC. It's fast, secure 
and easy to use. Download a free 
evaluation today! 



www.thursby.com 

Mac k a traderriork of ApdEe Computer, registered In ttie U.S. 
and oltier countries. The Built for Hac 0$ graphic a trademarik 
of Apple Computer, inc.^ used under license. 

DAV^ Is 0 registers trademark of Thursby Software Systems, Lnc. 

^ 200Z, Thursby software Systems, Inc. 









Request* R^requeata: 
long teacherld^ 1; 

for (long i=0:i<nuniRequests;l-H-,R++) 

I 

teacherName“R’>Haiae (}; 

If (strciip(lastTeacherName,teacherName)) 
[ 

last Tea e r Na aie-t e ache r Name: 
teacherld++; 

1 

R - >SetTeiopreacbG rid (teacher Id); 

char* childKame'^R-^CbiidNaiiieO i 
Child* chilii-FindChil<i(childNaiiie); 
asaert(child): 

R->ReplaeeCh:lidNaBia(child); 
child'>SetParentAvailabllity(): 


niiinTeachera“teacherl{t+l j 
try { 

teachera^ew Teacher [nuroTeachers] ; 

] catch(*.,) I 

Error (■’Could not allocate storage for”.’'teachers'*); 

) 

long lastTid*-1 ; 

R~requests: 

for (long i=0:i<numRequeste;i-i-t.R++') 

[ 

long tld"R )TempTeacherId(): 
assert(tid^numTeachcrs); 
if (tid 1“ laatTid) 

I 

teachers ttidl ,Inlt tR->NaBie(] ^tld): 
lastTld^id: 

) 

H'>SetTeachor(teachers+tid): 

I 

I 

void CombineRequestsO 
// Entcned with (tque^s alfcudy stoned liy leachcr. 

// For Mch teacher's Nock of request, sorts by patent, 

// Combines equivaJent rcqiicsts (same teadiet same parents, sutns priorities) 

//All absoribed rcqiK'Sts are marked with negative priority 
I 

Request * stCTequests :// read from 
Request * end-numRequests+requests : 
for (Int l=^0:i<nunTeachers:it+) 

( 

long 

tiuinSflffleTeacher^ountftyTeacher(src*end .iteachers llj): 
qsoft (sre. tiumSameTeacher»sizeof (Request),Request::CmpParents): 
Request* uniqueRequest“src: 

for (Request* R-src+l:R<src+numSameTeachGr:R++) 

E 

if (Request: ICjitpParents(RHmilqueRequest)) //if they difter 
I 

uniqueHequest*R: 

I else 
i 

R->TransferPrioriiyTo(uniqueRequest); 

} 

f 

src+^nuniSajncTeacher; 

* 

) 

long NunAbsorbedRequestsO 

// Sorts requests by prkirity ^ counts Ihc tail of 1 priority (nonLlniquc) requests 
// returns the number of requests that can be dropped 
( 

qsort(requests,numRequests.si^eof(Request), 

Request:iCmpPriorltiGs): 

Request * K“requests-HimiRequests; 
long numDropped^O: 

while ((R>requests) && (-^R)->Friority () < 0) 
nuBDropped+4; 


return numBropped: 

J 

void AHocuteConferencesO 
//llicre can not be mote than munTcachCTs'numlVriyds coitfcrences 
// unless one were to allow multiple parents to attend the same conference. 

// This does not sttpport multiple etmferenccs at the same time. 

I 

numConferences=l+nuiaTeachers*nuiiiPerlods://1 extra for [OJ localion 
try I 

conferences=new ConferenceInuarConferencesl; 

memset(conferences,0.s1zeof(Conference)* numConferences): 

I catch(*.♦) I 

Error ("Could not allocate etoroge for**r”cotife!:encefl''): 

j 

// address as LonfercneesI teachcrNrimimPCriocIs + periodNumher] 

// block pitch is numPeriods; conferences[0| is not used. 

I 

long FopulateConfetences0 

// Simple fiist come, first servedjower avaitability and higher priorities first. 

//After aiasifming requests to conferences, the request array must not change 
// Returns the simple score {sum of priorities of requests accommiKMed). 

1 

long numTQSort"(iiumConferencefi ■ 1 < uunR^questa)? 

{nuaiConferenci3n''l):numRequests: 
qsortlrequeEits^nuniToSort, si aeof (RequcEt). 

Request: :CjnpAvallability): 

Request* R=requests: 

long score=(}: 

long nij 0 iAHsigned“O; 

for (int 1~0:1^numRequests;i++,R++) 

[ 

Teacher* teacher"R >7heToachGr(): 
long teacherld"teacher )Pld(): 
long priority“R->Priority0; 

ConferencEJ* block===conferGnces+teacherld*nuniForlods: 

// lltid first free corifcretx'e 

for (int periodlndex^l 1 period!ndex<=nuniPeriods: 
periodlndex^H') 

I 

long perlt>d“afiSiftnlientOrder [periodindex] t 
if (block [per iodl - IsAssignedO) 
continue: 

Parent* pareiit=H >Ge t Avs I lablePa rent (period): 

if (parent) 

I 

block [period]. Ini t (teacher, parent, period , priority): 
parent ->Booktblock4-period,period): 
score+=prlorIty; 

numAssigned++| 

R'>SetPeriod(period): 
break: 

I 

I 

if (numAsslgned >“ nutuConferences-1) 
break: 

] 

return score: 

] 

void ReduceWai tsO 
//Tries easy ways of reducing waiting timc,s: 

// movipg to a dUfirrent time (agreeable to N>th parent and teacher); 

// inmsfCTring a coofcrencc to a spouse; 

// swapping time slots with another parent {same teacher), 

// These operations affect eacli otlicr ami arc repealed until no more 
// improvement can be obtained. 

// ADDED in version 2: 

// canccllirig a scheduled conference if that generates a points ath-antage, 

( 

long accinnulatedReductlon; 
do f 
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Made with 



REALbasic® 

- 


REAL Software and MacTech present the REALbasic Showcase to 
highlight some of the fantastic solutions created by REALbasic users 
worldwide.The showcase illustrates die wide range of applications that 
developers using REALbasic can create. Some benefit any Mac user, and 
others are more specific. All of them are seriously cool! 

REALbasic is the powerful, easy-to-use tool for creating your own 
software for Macintosh, Mac OS X, and Windows. It runs natively on 
Mac OS X as well as earlier versions of the Mac OS. For more 
information, please visit: <www.realbasic.com>. 

The Made with REALbasic program is a cooperative effort between 
REALbasic users and REAL Software, Inc. to promote the products 
created using REALbasic and the people who create them. For more 
information about the Made with REALbasic program, please visit: 

<www.realbasic.com/realbasic/mwrb/Partners/MwRbProgram.html>. 





REALBASiC SHOWCASE 



Extend REALbasic with 
Advanced Plugins 

Spreadsheet Controls: 

We provide a wide range of spreadsheet controJs for 
REALbasic, including multistyled and custom rendering 
spreadsheet controls. 


A 

1. B 

1 ^ 


TKTi" 

is some mere 

dihie list 


Go 1 

Seen* tixl 

Mar* tvxt 


Z 

testi 

lift re text 

G& ^ 

SapnrtBxl 

More text 

^ 4 

5c mi Usd 

More text 

^ S 

SomUsd 

MoretttXt 

P 

:'Ji 

1 

6 

Some text 

('tore text 

Oa 7 

SsiiHtfjd 

More text 


a 

Somt1«cd 

Merc text 


_ 



• More than 32k of rows. 

^ Classic, OS X and Win32. 
^Accelerated for maximum 
speed, 

II * Images in cells. 


OllOOlO 


Cryptog ra p hy: 

We provide data encryption, encoding, 
compression and hashing for REALbasic. 

Supported Algorithms: 

• Encryption: 

- e-Cryptlt 

- BlowFish (448 bit) 

-AES (Rijndael) (256 bit) 

• Encoding: 

- e-Cryptlt Flexible 

- Base 64 

- BinHex 


- MacBinary III 

- AppieSingle / Double 

- UUCoding 

• Compression: 

- Zip on Strings and streams Iqz) 

* Hashing and Checksums: 

-CRC32/Adter32 

- MD5 / HMAC„MD5 
-SHA/SHA1/HMAC SHA1 


Other Plugins: 

We have many other 
plugins for REALbasic, 
including plugins to do 
advanced MacOS 
Toolbox tasks and more 
custom Controls. 



Speed up developement and make 
more advanced applications 
by using plugins ! Get free demos 
at www.einhugur.com 



Einhugur Software 
sales@ein h ug ur .com 
www.einhugur.com 


Corona 


accounting sg/hoare 


"Eas>^ to set up, easy to use, 
and excellent support from 
the developer.” 

Five stars ou VersionTracker.cotTi 



cash entry 
• invoicing 

• payroll 

• reports 


$49-95 


• account chart 

• address index 
• help facility 


Free 30-day tria! 

http: / /homepage .niac.com/ id le wild /CoronaUS. h qx 


A best friend for business! 

P.0, box 3164 • oewti^rg ■ Oregon • 97132 

idtewild®mso.com 




Picture Play 


Crc^c (imital coib^^cs on your Mac. quickly and easily 

Cimtm: dipurl. ormythmK eht mimAciX iKtri rm* 

fioy h mimw W m he med h 

hmnufMti'ompks thm^t nm minmtHhe 
iittm roiiie, h \ktUkiyokmiiL:*mkf^ctMpoynnms mttry iiafffy jHm ifftr 

Only I SSID, r«r Mif 0S9 tad Mk OSX 
(licckil Q«l by KPina l» 
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REALBASK SHOWCASE 



Advertising helps you build your brand. After alh you 
don*i expect someone tobuy your product if they’ve 
never heard of you, do you? 


Alt products/services made with or retaiedto REALhasic 
qualify to be a part of our exclusive marketplace section. 

Are you looking for extremely small out of pocket 
advertising that will reach your target audience? 

We bill you for ads monthly as each issue ships. 
Contact our ad sales team today for more details. 

Volcez 005-494^9797 x113 « eAAailiad sales@tnactech.com 



ww w.m a cte ch. CO m 


ERT ELECP DEfitSN 

FonfViewer 

FontViewer is a simple but elegout hnt vrewer that allows you to 
preview all fonts in your fonts folder They can be displayed in 
various sizes and styles with the click of a mouse^ FontViewer aha 
features the ability to display your fonts in a slideshow, and view 
your fonts in almost every type of environment possible (i.e 
desktop, menus, icons, etc.) 

Creative Box URL; http://www-creaHvebox,net/ 
Developer e-mail; jason@creaHvebox.net 


piDock 


piOock is the mivsl have novigofion and launching utility for 
A/lacOS. Now you can easily organize, navigate and launch 
files with a simple sweep of the mouse. 

Compatible with OS 8,6 through W.J, OSX users con now 
control-option click a folder to navigate ith contents. 

http;//www.pidc»9.com • http;//www.pido€k.com 
_ piPock@pidog.com _ 




" 





/Screensaver 

designer 

for MocinfosA dnit Wiht^pws^ 



rfTT 

_ ^ -rtii sa^mvers 

MrfKMJT touchtiif^ a 14fl'>Kfa»“S modvoe 


the world's only cross-platform 
screensaver design tool 

• build both Macintosh and Windows screensavers 
with a single dick, on whatever system' you are using/ 

• use any QuickTime movie format : 

Macromedia Flash, MPEG, Cinepak, MPT, Midi, AVI, DV Video... 

• include a hidden movie that can be unlocked 
with a registration code 

• customize and fully-brand both Installers 
and Screensaver control panels with pictures and text 

• screensavers install without DLLs, extensions, or restarts 


simple 

WYSIWYG 

editor 

supports 
interactive Fiash 
and QuickTime 

consistent 
cross-plattorm 
user interface 

try before you buy 
fatty functionai 
online downioads 



tfie jSk'je&isavef Deing/ter editiiig e^miufmterit 


http :/iScreensaver. net 

email : info 0 iScreensaver.net 


* supiwrted systerns, as of Novefnber 2001, include: 

Maciniosh OS 0.6 to 9 2 , Microsoft windows 95/98/ME, NT^/NT^CK30/XP 
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.^(PpSoft 


StimpSoft™, Inc. 


StimpSoft^^f fnc. Maters of insanely 
mediocre software for cats, dogs, voles, 
wallabies, mangos, crkkefs, and 
people. We put the in ”Software". 

URU Kttp://www,stimp50ft*<om 
Email: john@stimpsoft.com 



obDataTools 


db Reports is o cross-platform report writing application oble to 
extract, format and print dota from one of various data sources. 
A multitude of built-in features and expressions make db Reports 
a powerful tool for analyzing data. 

Free demo and more defoiis locoted at 
http;//abDataTool5.com 



MAC MUSIC MANAGEMENT FOR 
SONY*^ 5 TO 400 DISC CD CHANGERS 


Control up to 12 changers (4,800 music CDs) 
Control Any Brand Stereo Receiver r 
^ , Play MP3 and other Sound Files 
'''-J. Plus much, much more!!! 


wwviirJtltletradi^dsm info@titietraclc.com 


Whistle Blower 

Enterprise server monitor and restart utility 
whisrieblower.sentman.com 

Connect to and validate the response from web servers, 
cgi scripts and over 23 other types of servers. 

Send email, pages ond perform unattended restarts via 
MasterSwitch or PowerKey. 

Shifts make sure that the person on call when the server 
goes down is the one who gets the page. 

68k, PPC and Carbon 

Web based administration lets you check on and restart 
your servers from anywhere. 

Customize your response to an outage with Apple Script 


email us at whistleblower@sentman.com 



6ota; 

wvm.devdepot.coni/realliasicfoiilunimles 

and buy today for over $8 off retail orice! 


Available While Supplies Last! 

lor . 1 * ' i( r t '■ L ■ ‘ T t * i ■ ■ ft T h ^ 'S 'Ll' - Sk ■■■! 
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accumulatedReductlon “ ReduceWait^ByTiro«Chan^iet): 

lori^ reduction; 
while (0 < (reduction = 

Reduc uFa rentWali s ByTrunsfera{))) 

ac cumulatedReduc t iou^raduc tion: 

accumulatedReduction += ReduceFarentWaltsBySvapplngO: 
1 while (accuiiiulatedReductio[i>D); 

RGducePenaltyByCanceilatlonC) * 

1 

Child* FindChild(char* childName) 

// iind;^ a ctuld record by 
( 

Child EearchKevCchildKame,0,0,0): 
return (Child*) 

bsoa rch (&Rea rchKey .child ron, nuroChi 1 d ren, e i zeof (Child), 
Ci5ip<Child>) : 


Parent* FindParent(char* parentName) 

// FindN a pareni rcconi by name. 

I 

If (parentHame) 

I 

Parent aearehKey(parentName,0.0,0): 
return (Parent*) 

bsearch CSsearchRey,parents,nuraParents,sizeof(Parent), 
Cmp<Parent>): 

I else return 0: 

1 


long CountByTeacher(Request * ft,Request' end,Teacher' 
teacher) 

// Returns the numl)cr of icquests for otic icadicr, 

I 

long couTit**0: 

while {(R(end) Si ((Rt+l->TheTeacher t )^^eachRr)) 

COtmt++; 

return count; 

1 

long ReduceParentWaitsBySwapplngC) 

// Aitcmpls to swap confcrcnccji with the same teacher, but between dirfetrent parents, 
// if tlvat results in a reduction of waitinf penalties, 

// Returns the reduction achieved, 

I 

long reduction^O: 

for (Conference* hiock“confereaces; 

blockiconferenceff+nuMConferences-1:block+=numPerlods) 
I 

for (long periodl"!:periodKnumPerlods:periodl+i) 

[ 

Conference* €l"block-»-poriodl; 
for (long 

periodZ^perlodl+^I ;pei:lod2<^nuiisFeri£>db”period2++) 

Parent* Fl=Cl->TheParent(): 
if (!P1) 
continue; 

If (Pi >TeBQ0kedCperiad2) || iPl- 
> IsAvailable (per 1 od?.)) 

continue; 

Conference* C2=block+period2; 

Parent* P 2=C 2 -> The Parent(); 
if (EP2) 
continue: 

If {P2'>IsBooked(periodl) j| 1F2- 
>InAvaiIrtbln(period I)) 
continue: 

long before=Pl >NuraldleFGriods()+P2 
>NuflldlePeriods(); 

if (before<K)) 
continue; 

Pi->SMapConferenceCperiod!.P2,period2); 
long after^Pl ■ >Nu!nTdlcPeriods()+F2‘ 
>NuinTdlcPer”iode{); 

If (after <= before) 

I 

Cl'>UpdateParent(P2); 

C2->tJpdateParent(Fl); 


reduction beiore’after; 

i else // swap buck 

Pi ->SwapCoQference{peciod2,P2,period 1): 


retiLtn teduction; 


long ReduceParentWaitsByTransfers() 

// Attempts to reduce waiting penahks by assigning ctjnfcrenccs U) sptuisrs. 

// Returns the reductkin aebieved. 

r 

long redtiction=0: 

for [Conference* C^conferences; 

C < c on f e r enc e e+n umCon f e re nc e s:C'H') 
f 

Parent* P=C->TheParentf): 

If (IP) 

continue; 

Faren t ‘ spouse^F >Spouse(); 
if (Ispouse) 
continue; 

long periodic->Petiod(): 
if (!spouse^>IeAvailable(period) {I 
spouse'>rEBooked(period)) 

continue: 

long before*^? >NujnrdlePeriodsC) + spouse^ 
>NumIdl€PeriodsO; 

if ((before<=0)3 
continue; 

P‘>TransferConferenceToSpouse(period); 
long afte£=P*>!lmiiTdlePeriodfl () + spouse- 
>NuiaTd1ePerlods (); 

if (after <= before)//update conference with transfer 

t 

C->UpdateFarent(spouse); 
reduction+“before-after; 

I else 

spouse->TransferCoTtferencpTo,?pause{period):// tiadci 

transfer 

) 

return reduction; 


1on g Red uc eWait s ByTime C ha n g e() 

//Attempts to reduce waiting penalties by shifting conferences to different peri(KlfL 
// Renum the reduction achieved. 

I 

long re(liiction=0; 

for (Conference* C^onferences; 

C<confercnces^umConferences:C++) 

( 

Parent* P=C->TheParent(); 
if (!P) 
continue: 

long busLPerlod^C )Pcrif»d (); 

Tea che r * 'l^^C >TheTea c h e r (1 : 
assert (T) ; 

Conference* teachersBiock=conferences+T- 
>Pid() *ni]raPerioiis; 

long lowestWait“P'>NunIdiePerioda{) i^TeacherWaits (T): 

If (lowcstWft |T<=*0) 
coruinue: 

long beforE^lowestWait: 

for (int alternatePetiod=l:alteniatoFetiod<“numFeriods; 
alternatePeriod++) 

I 

if taltert>atePeriod="bestPeriDd) 
continue; 

If (F >raAvailablo(altcrnatoPcriod) 

!P->lsBoaked(alternalePerlod) 
iteachersBIoc k[alterna tePerlod j,IsAasigned()) 
i 

P- 

>RcschcduleConferencfi(bestPeriQd.alteniatePetlod); 
teacbersRlock[alternatePeriod]. 

Copy(teachersBlock[bestPerJod),altcrnatoPerlod): 
tGachersBloeklbestPeriodl,Clear(): 
long wait^P->NuDildleFGtiods()+TeacherWaics(T ); 
if (w3it<“lowestWait) 

I 
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lo¥estWait“¥ait: 
bf! Rt Pe r i od 1 te rn a t ePe r 1 od j 
) el se // tinclti ihc itscbeduling 
t 

P' 

^Resch€duieConference(alternatePeriod«b€$tP€riodj ; 
taacheraBlocklbestFarlodl. 

CopyCteachirsBlockfalternatePerlodl.bestPerlod); 

teachersBlock[alternstePerlod].Clear ()t 

I 

\ 

I 

reduction += before-lowestWait; 

I 

return reduction: 

I 

long Reduce Penalt yByCancellation( ) 

//Attempts to reduce waiting penalties by cancelling ctmfcienecs cntinri>. 

// Returns titc reduction acJikved. 

I 

long reduction-KJi 

for (Conference* C“conferencea+l^ 

c on f e r e n ces+riuniC^ n fe r e n r. e R t C++) 

( 

if (ICMsAssignedt)) continue: 

Parent * P=C ->TheFareut(); 

Teac h er * T”C-> TheTe ac ber(): 
long priocity“C->Priority(); 

long waitBefoce“F->NmaldlePeriods()+TeacherWaits(T); 
long perlodH3->PeriodC): 

P - >Unb ook (pc r i od 1; // caticcl ainfcrencc 

C >ClearC): 

Long vaitAftec=P->riluroidlePeriodst)+TeacherWaiis(T): 

If (waitAfter < waitflefore-priority) 

f 

reduction +- waitBefore-priority - waltAfter: 

1 else //reestablish ainfcicnce 

[ 

P >Hook£C,period); 

G->lnit(TiP,period.priority): 

1 

1 

return reduction: 

I 

void SendConferencesO 
// S<^tltls tlH‘ confrrrncc scheclute ui the output file. 

( 

outputFile.OpenC): 

for (int i“0;l<nuroConferences:i+-*-) 

I 

if (conferences f i]. IsAssignedC)) 

I 

oulputFIle.ScndConferenceCconferencesli ])t 

//Versiem 3^ 

// U‘t sp^iusr join a confcirncc if that rrdiKCs waiting time for tlw^ spiHise. 

Parent* spouse=conferences [ij .TheParent f} *>Spouse() ; 
if (spouse) 
t 

long period=confcrences[i].Period()t 
if (fipouR0->lfiAvall3hle[period) && 

! spouse >IsBookcd (period) tik 
// niaki- siia' extra conference improves spouse 's schedule 
(period ( spouse->LastPeriodUsed()) kk 
(period > spouse->PlrstPerigdUsed{)} 

) 

I 

//We just rtpljice parent with spouse since parent's confetence is already recorded, 
conforcncestil .UpdaieParcoL(spouse): 
oiitputPlle.Sc[idConference(ct)iifereiiccsliJ); 

I 

I 

I 

I 

outputFlle.Clone(); 

I 

long TeacherWaita(Teacher* T) 

// Assumes the confcrcncc array b laid out as rows of lumiPcriod conferences per 
// teacher. Returns die nutnlier of idle periods of one teacher 
I 

long teacherTd“T">PidO : 


long teacherfirEt“nuiiPerlods+1: 
long teachetLast=^; 
long teacherNunrOi 

Conf erence * block"€onfe rences+teache tId * nunPeriods: 
for (int perigd=I tperiod<“nuniPeriods:period++) 

I 

if (blocklperiodj .laAsGignadC)} 

I 

if (periodCteacherfirstJ teachetfirst^period: 

teacherLast”period: 

teacherNuii++: 

I 

I 

//1 IXkU in version 2; c;ontct output (0) if teacher b rurt assigned any confeitnce 
long teacherWaitfi“(teacherrJum) 7 

(t eacherLast+1* teacherfirat-1 eache rNum):0: 
return teacherVaitB: 

I 

h 


int mainO 
I 

long nuiiiTeatE“InputFile:: CetNuaiTeats (): // get the 

number of lesis 

LogFile logFile(nuiaTGsLs); 

for (long tesT:Nujriber=l;testHuinber<^uiBTests:tefitHumber++) 
// kiop over the number of tests 
I 

HyTimer timer; // starts a timer 

TfvatCaao teatCaGeCteatrfuniber): // conttmeu a text case 
testCasc.RunO : //runs ihc test case 

logFile. Se t ( If saves the liming in logFilc 

testNumber,timer.ElapsedMilliSecE()): 

I 

1 ogFiie. Send 0 : // sends the lugFilc to disk 

return 0; 

1 


PT“Persons,h 

jf^lfndef PT_PERS0NS_H 
^define PT_PEHS0NS_H 

/* person based classes for tin: Paicnl- lcachcr conferences V 

^include <atdiib.h> 

iffinclude <stdiQ.h> 

jlinclude <stEing.h> 

flinclude <ctype.h> 

iPinclude "PT compile constants.h” 

^include **PT-yi ill ties,h" 

enuiD f 

kLineLength“255. 
kLineEnd*^xOD // Mac line end 
I: 

class Request: 

typedef Request* RequestPtr; 
elaes Conference: 

typedef Conference* ConfereneePtr: 
class person 

// Ihist' class, kntjws how^ to scan the icjti tfi extras The persons name. 

( 

char* name; 
ulong pid: 
public: 

PersonO inamefO) I I 

Fersonfehar* xnarne.ulong xld)jnamefxname),pid(xid)1) 
char* RameC) const |return name:) 
ulong Pid() const (return pid; I 

int operator - (Persons c) const (return 
St remp(name.r.name):I 

char* Init(chsr* cp^long xld) 

t 

char* line^LeflTrimtcp): 
name=iine: 
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liiifi-ForvrardTodlne, \ J 
‘1ine=0; 

HJghtTriraInane,line); 

pld*xid: 

return line; 

1 

Btatlc char* LeftTtimCchar* cp) 
i 

vhile t*cp Ilsalnum(*cp)) 
cp-H-: 

return epj 
f 

static void RightTrimCcbar' start*char* cp) 
// Sc;uis backwattl^, beginning at the null char beyond string 
1 

while ((cp>atart) && I IsalnunC*{-cp})) 
'cp=0: 


static char* ForwardTolchac* cp.char c) 

while (*cp U (‘cp i= c)) 
cp^: 

return cp; 


static char* ForwardTo(char‘ cp^ebac cl,char c2) 
while (*cp {‘cp J= el) kh t*cp c2)) 

cp++; 

return cp; 

1 

I: 

Ht MAXNUMPEHIODS <* 255 
typedef uchar period t; 

^define Period_FDRMAT "%hhd" 

HgI Be 

typedef long Period_t; 

#define Period.FDRMAT nid" 

#endif 

class Parent;public Person 
// ix>lkciii>n of pattntal fiincLitjas. 
i 

Patent* spouse; 

ConferencePtr* booked; 

// orraylnumPtTkidsl atlocaicd if/tt-^hca parent Ixxiks a conference 
Period^t firatPeriod; 

Perlod^t lastPeriod: 

Feriod^t firstPeriodUsed; 

Period,t lastPetiodUsed; 

Feriod^t nmaPerlodsOaed; 
public; 

Parent() ; 
apguEeCO), 
booked(0) 

n 

Parent(char* parantWame^long xid.Lcuig pi,long p2) : 

//Tlu^ constnicti^r is only used in making p searchkey hr bscardi 
PersonlparentName.xid)» 
spouse ( 0 ). 
booked ( 0 )t 
flrstPerlodtpl), 
lastPeriodCpZj, 

fIrStPeriodUsed(lastPeriod+1), 
lastFerlodUaed(O), 

// well rely on bstPeriodl iscil initiaJi;«ed to tJ to indkatc rwK'onfcatJLv 
mimPerlodsUscdSO) 

II 

"-Parent (J (if (booked) delete (] booked;! 
ebar* Initfchar' cp*Xong xid) 

// iraiudkoi cadj patent as port of reading the schedules fikr 
I 

char* llne^Person;ilnlt{cp,xid); 

eacanf (+^linc,PGrit>d_FORMAT’'. "PerioOORMAT.&flrstPeriod, 
blastPeriod); 

fira tPeriodUsed=lastPeriod+l: 

lastPeriodUsed^O;// wc'll nrly later on this having been jmtialj/4sl Uj D 

nuffiPeriodsOeed-O; 

line"ForwardTo(Une,kIine^nd); 

return llne+1; 

I 


Parent* Spouse0 const (return spouse;! 
void Harries (Parent * s) lapouse’^a:! 

const Parent* FirstParent{J const //mums pafcnt of higher address 
i 

if (this > Bpoufie) 
return this: 
else 

return spouse; 

1 

long FirstPeriodO const treturn firstPerlod; | 
long LastFerlodO const [retttrn lastPerlod;) 
long FirstFeriodUsedt) const (return firstPeriodUsed;I 
long LastPeriodUsed[) const [return lastPeriodUsed:1 
bool IsAvailablcClong period) const 

return (Cperiod>=firstPeriod) && (period<“lafltPeriod))i 


void Book (Conference* 0*long period) 
ri uHtPe r i od s U sed++ ; 

if (period>lastPeriodUsed]lastPeriodUsed-period r 
if (period<firstPeriodUEed}firstPeriodllsed“period: 
if (tbooked) 

I 

booked°new ConferencePtr [l+lastPerlodJ; 

(»CAset (booked ,0,siKOof(Conferen€eFtrJ * (1+lastFerlod)): 

1 

booked [period]=C; 

I 

ConferencePtr IsBooked(Period .t period) const 

if {period>iastPeriodUsed) return 0: 
return booked(period]; 

I 

void TransferConferencoTt>Spouse(ioiig period) 

assert{IsBooked C period)); 
assert(spouse); 

assert(1spouae->IaBooked(period)): 

Co n f fi re nee * C"='bo oked [period] ; 

tinbook (period); 

spouse rbookiC,period); 

1 

void liwapConffirenceCPeriod_t periodl. Parent* P2, 

Period..c peri5d2) 

I 

Conference* C1 “booked (per iodl]; 
assert(Cl); 

Unbook(period 1); 

Conference' C2=FZ >bookedlperiod2j: 
assert(C2); 

P2->linboek(period2); 

Book(C2,period!): 

P2 >Book(Cl.periodl): 


void Unbook(long period) 

I 

booked [period: J =0; 
if [period=firstperiodtfsad) 

( 

if (pGriod”laatPerlodlIaed} 

I 

f i rstPc r lod Used*"las LPer iod+l; 
lastPeriodUsed=0:// mnit 
I else 
t 

while {I booked f + (firstperlodUaed]) 
assert (firstPeriodtIr.ed<laatPcrlod); 

I 

t else If (pcriod“lastPeriodUsed) 
t 

while {! booked l-iastPeriodtlsed j) 
assert (lastFeriodllsed>firstPeriod); 

) 

ntifflPe r iod sU s ed“; 

) 

void RcscbcdulcConfercncedong oldPeriod ,long newPerlod) 

Conference* C=boaked[oidPeriod] ; 
assert(C); 

Unbook(oldPeriod): 
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sssert 11IfiEooked{nawPeriod )}: 

Boak(C,ncvFeriod )i 
I 

long Nunldl^PeriodsO const 

I 

long Tiumldl^O: 

If (lastPeriodUsed) 

num I d ie“ 1+la s t Pe r i od Us ed - f 1 rs tpe riod Us ed - 
numPeriodsUssd i 

roT.yrn nujoTdlc; 

J 

void SbotfU 
f 

priiitf("Ss, ti, %d\n*'.NawsO ,firstPeriod.lastPeriodJ: 

) 

I: 

class ToachofI public Fexson 
// Collection of tochers functions, 

// In this jjrogntm. teachers have no fiinettuns, and aic just persons. 

I 

I; 

clann Childipulil tc PRrson 

// Converts patent names into pointers tt» pan^nt recortis. 

// CoUcetion of child hinetkins, mostty ahont their patents ihough 

I 

union 

I 

char* parentlName; 

Parent" paranti; 

1; 

union 

I 

char* pa[aui2Nuiuc; 

Parent* parent2; 

I: 

Period^t pa rentAvailahility: 
public: 

ChildO ; parent ((0}, parent2(0) 11 

Chi Id(char* eh1IdNaran*long xld*ebar* pi,char* p2| : 
Person (chlldNauio*xid) , 
patentlMaaietpl), 
parentZNumeCpzi^ 
parentAvallability(Q) 

I I 

char* Inltfchar* ep,larig xld) 

I 

char* 1ino"Porflon::Tnlticp,xid): 

lioe-LeftTrindine+lJ: 
parentIName^line: 

line^ForwacdToCline,*,'.kLineEndl: 
bool second Parent" C*llue==V,"): 

RightTrlii£parcnt INnroe, line) j 

If (ueeondParent) 

I 

iine-LeftTria(iinel'l): 

parent2Harae“line: 

line=Fo rwardTo Cline,kLineEnd): 

*llne"0: 

H|ghtTrIm(parent2NaiiieN line) : 

] else pafetiL2Nunie^0i 

parentAvaliabillty'=0 \ if not known until parents are linked 
return line+1: 

) 

char* ParentlNameO const I return parentlHaroe ;) 
char* Pacent2NaBieC) const Ireturn patent2HaiEe: 1 

Parent* ParcntlC) const treiurn parent!;1 
Parent* PatrentZC) const I return parent!;) 

void RegisterParentsCParent* pi,Parent* p2) 

I 

assert (I at reap Cpl->NaineC) ,parentlNaine)}: 
parenti=plI 

if Cp2) 

assert £ lstrcrap(p2->Naine £3 * parentlKaaie)) : 

pureut2^p3: 


I 

) 

void HarryParentsC) 

* 

assert(parenti)t 

Parent * apoosel“parentl - >3potiae () 1 
if (parent!3 
I 

Pa rent * spouse2*parent2' >Spouse f): 
if £!spousel lspouse2) 

I 

purcnLl >Hacrlcs(parc[n2); 
parent!->Harrles(parentl); 

1 

I 

I 

long ParentAvailability() const Ireturn 
parenrAva Habil i ty: I 

void SuiPurent Avallability£5 

// because of ixi!tsibly mixed parent sets, iliis needs to bc‘ computed for each t liild 

I 

parentAvailability'^ojsputeParentAvai labil ity (3: 

I 

long ComputeParentAvailabilit y() 

// returns ttJtal number tif periods either parent is availal^fc 

I 

Jong pi firs L=pateiiLj >FlretPerlod {) i 
long p llaat=parent 1 - >Last Per iod (}: 
long pllength=^l+pllast - pj first ; 
if (parent!) 
f 

long p2firBt=parent2'>FirstPeriodC3; 
long p21aat=parent2->LastPeriod(): 

Tong p2lcngth=Hp2laat p!firsr 1 

II (plflrgi<-p!firsi3 

I 

If Cp2first > pilast 3 return pllength+pllength: 

// disjoint or cxjtitiguous 
if £p2first <" pliaat) 

if (p21ast>pllast3 return l+p2la«t-pl£irBt: 
oIkc return pilength: 

I else //p2fiT>ti <plfirst 

I 

If (plfirst > p21ast) return pilengthtp!length: 

// dkijoiut or contiguous 

if [plfirst <= p2iafit3 

if tpllast>p21ast) return npllast-plfirst: 
else return p2length: 

1 

1 

return pJlength; 


Claes Eequest;public Person 
//Teachers name fmm file is stored in Ptn«>n. 

// Expansion of the data gathered frtjm the teachers file 

I 

ulong t empTeac ho rId; 

Teacher* teacher: 

union 

[ 

char* chlldNaiae; 

Child* child: 

h 

Perlod_t assignodPerlod: 
long priority: 
public: 

// Wc rely on memsciO to clear all to (3 wlien att array of Requests is alloc’uted 
char* Init£char* cp,long xid) 

I 

char* line"LeftTrlm(cp); 
ehlldRaHc^line: 
line=^ForwardTo £liiie / / 3; 

*iine-[J: 

RightTriEi{chiidHaroe,iine3: 

llne=Person::Inlt(line+i,xid): 
sscauf (++llne, "Itld**, Apriority) : 

11 n c-Fo rva rd To (11 no, k 1, i noE n d 3: 
return line+1: 

1 

long PriorityC) couut Ireturn priority:! 
void ReplaceChiidName(Child* c) 
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assert tJatrcmpCc-^NaweC) ♦childUajne)); 
cliild=c; 

I 

ulDng Te^pTeacherldO const 1 return tempTeacherld:I 
void SetToaipTeacbetId {along tid) ItempTeachecId^id: 1 

Teacher* TheTeacbcrO const {return teacheri{ 

chat* TeacherNaaie() const I return teacher >KaiQeC): l 

void SetTeacher(Teacher“ theTeacher J[teacher*theTeachct 1 1 

char* ChildNemeO const I return childNameH 
Child* TheChlldt) const I return child;) 

Parent* FarentlO const {return chnd->ParentIf) : 1 
Parent* Parentsf) const (return child >Parent2();i 
Parent * GeLAvailableParEiilflong period) const 
( 

Parent* parent=Parentl(); 
if {parent *>lEAvaiiable( period) Iparent- 

)IsBooked < pe riod)) 

return parent; 
parent**Parcnt3{); 

if (paronl && parent >IsAvailable(period) && 

I parent->IsBooked(period)) 

return parent; 
return 0; 


long ParentAvallabll ity f) // piccomputcd for aJI parent pain; ahcud nf time 
// mums number of peftods eiihcr paitmt b avaikbtc 
{ 

return child->PareiitAvai lability t); 

I 

void TransferPrlorityTo(Request* unlqueHequest) 

I 

unlqueRequest Apriority priority: 
priority" 1: 

I 

long IsAssignedf) const I return assignedPeriod:] 

void SetPeriod(Perlod_t period) lassignedPerlod^period:I 

static Int CnpParents(const void* a♦const void* b) 

// compares pare nts simply by thdr address in memory 

Request* ra-fRequest*)a: 

Request* rb^(Request*}b; 

int d"ra->parent{() rb->Parentlf); 

If (d—0) 

return ra >Parenl2{> rb >Parcnt2(): 
return d; 

J 

static int Carp Priori ties (const void* a. con at void* b} 

// liighcsL priority first 
t 

Request* rft^(Rcqueat*)e; 

Request* rh"(fiequeflt*)b; 

Int d*fb >ptlQrlty ra >priority: 
return d; 

I 

static int CapAvailability(const void* a,const void* b) 

// lowest availability Hrst, then highest priority 
I 

Request* ra“(Raquest*)a; 

Request* rb“{Request*)b: 

int d"ra >PareniAvailabillty0■rb ^Parent Avail ah1lity(): 
if Cd“0) 

I 

d-rb Oprio rity - ra - >priority; 

I 

return d: 

I 

I; 


class Conference 

// Holds dau defining a conicrimcc. 

// Collection of confcitncc rebted hEnctlons. 

{ 

fcacber* teacher; 

Parent * parent; 

Period_t period; 
long priority; 


public; 

Teacher* IsAssignedO const (return teacher:) 
void Init(teacher* I♦Parent* p,Pcriod_t x,long y) 

teacher=t: 
parent“p: 
period=x; 
prlority=y; 

void ClearO (Init (0»0.0,0): I 
void Copy (Conferetice& GiPeriod_t x) 

I 

teacber=C.teacher; 
parent=C.parent; 
period=x: 

prlority“C.priority; 

Teacher* ThcTeacherf) const (return tGacher;| 

Parent* TheParentO const I return parent:! 
const Parent' FirstParent() const 
I 

assartfparent); 

return parent->FirstFarent(); 

I 

long PerlodO const {return period:) 
long PriorityO const (return priority;I 
void UpdateParent(Parent* p) {parent=pil 
int operator - (Conferenced r) const 
I 

Int d“r * pa rent'>Flrst Parent {) - parent‘^FirstParentO ; 
If (d=0) 

return perlod r,per1od: 
return d; 

I 

); 

fendif 


PT-Utilities-Cpp 

/* Some basic utilities. 

Mostfy sclf-cxplanojoty. 

V 

^include <string^b> 

^include “PT-Utilities.h’' 

void Errorfehar* si♦char* s2} 

( 

prinLf(l*%s %s\ii**.sl *s2): 
exit(O); 
i 

void Error(char* si*long x.char* sZ] 
I 

pr Intf (*%s1td%e\n**,sl ,x,s2); 
exitfO); 


long FileSiaeCFILE* f) 

f 

long curPoa“ftell(f): 
fseek(f,O.SERK_EHD): 
long slze^fteli(f); 
fseek f f,cur pQs,SERK_SKT): 
return size; 


PT-Uttlities-h 

ilfifndGf PT^OTILITIES^H 
Ifdefine PT^UTTLTTTES H 

r 

Prototypes of utilities, and a generic comparator 
Mo;»lly scJfcxpiatMitory, 

V 

rf^include <stdio,h> 

#include <sti!lib»h> 

typedef unsigned char uchar: 
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typedcf unsigned long ulong: 
lypedef unsigned short usbort; 

void Error(char‘ si»char' s2j: 
void ErrorCchar* si. long 3t,char* s2): 

long FlleSl7.e(FTLE* f); 


lesiplaie <class T> 

inline int Cmp(const void* a,const void* b) 
// Generic comixirattir for qsort ind l)$t:arch 
// Uses opemor - of <1> for tlic actual comparison 
I 

return - ‘{(rib); 

1 


#endif 


PT-Files.h 

#ifndef PT_FILES_H 
^define Pr_FILESJJ 

r 

Fik dasfies. 

Mostly self<^planatorY 

V 

^include <Etdlib.b> 

^include Cetdio.h> 
j^include (string,h> 
include <ctype,h> 
fine 1 ude " FT ■ couspi 1 e - constants, h ” 
include “FT Persons.ir 

static ebar inputFileNaaie^] =lHPin‘_DlR15CT0Ri'“inputt tJCt” ; 

static char cbiidrenFiieNanie [J 

-INPlJT„DIRECrOEY"childrenWN,txt”: 

static char teachersFileNatfle(] 

=INPllT^DlKKamY“tcachorsNN,txf: 

static char schedulesFJleNarie [| 

-INPUTJIJKKCTOKY'schedulesNN. Lxt" ; 

static char outputFileNaiite[J 

-INPUT^DlRECTOKY-conferencesNN.txf: 

static char logFileNaJue[] -INFtfT_BIPECTORY"log,txt"; 

finuB lkOutpvitF11efiufferSixe=1024): 

inline void SelFllenmoefchar* name.unsigned long number! 

// Rcpacit^ NN with a 2'djgit number in a fik n^mc 
( 

assert (nuiiber<“9 9) \ 
int len“strlenCnaiDe): 
assert(lfin>-6 )i 
char mW; 

spr^ntf(NN.■•Wd^nulabo^)^ 
namellen 6]-NN[0]i 
numeUen S] "NN [Ij r 

1 

class InputFlle 

// Only U!icd to read the mimbcr of icMs, 

i 

publici 

s la tic long GetNuaiTestsO 
t 

FILE* t=fopentinputFiieNa[Be."'rb"): 
if (If) Error(inputFilelJame.’*not found*); 
char linerkLlneLengtbtl]^ 
fgets(line,kLlncLength,f); 
long numTests; 

sscanf(line,"%ld* * knumTests): 
fclose(f); 
return numTests: 

1 

1 : 


class Tex[File 
// Generic ancestor for text fiks. 

// Reads the eiiLiie lik Into memory. 

// Derived elii&scsi arc rcquircd to pirsc tlic text in memory, 
i 


long capacity; 
char* filestore; 
public: 

TextFiieO : fileSioreCQ) II 
char* FileStoreO const (return filestore;I 
long Capacityf) const [return capacity;! 
long Read(char* filename) 

// rcark fik into filditoa' 
f/ returns mimber of ttntt lines rcid 
I 

FILE* f=fopenCfileNBme.*rb"): 
assert(f); 

capacity=FileSi 2 e(f); 
try I 

fileStQre=new char | Hcapacity] ://add 1 for NULL char at end 
f C0tch(, .J I 

Error("Could not allocate storage for",nieKamc); 

long iiumKead=f read (filestore . 1 ♦ capacity. f); 
assert (capacity = numRead); 
fcIoseCf); 

f ileStore fcapacltyJ-O;// /cm terminate 
return LineCount (3; 

I 

-TexlFileO 

I 

if (filestore) 

delete [] filestore; 

fileStote-O; 

I 

private: 

long LlneCount ()// assumes single line cod character (Mac) 

I 

char* cp^iieStore-1; 
char c^*cp: 
long count-0; 
while (c) 

[ 

if Cc”=kLifieEnd] c0unt ++: 

C”* (-H-cp ] : 

1 

c=* C-cp): 

if (c !“ kllneEnd] countit; 
return count; 

[ 

I: 

class ScheduleaFlle:public TextFile.public Person 
// Rr^uhi dte Kl-scficduks fik and ^.irts parenti Isy name. 

// IVrson clajjs contains llwr^Forwaitnb'' fumiiori rcqtlircd herc, 

( 

Parent* parents: 
public; 

£chediileEFile(long LestNumber. long^ uumPerlods, 

Parent* & xparents.longi numPareats) 

SetFilename(schedulesFlleName.t es tNumber): 
numPa rent s=Re a d(sche d u1es F11eNa me)-1; 
try ( 

parents=nG¥ Parent[numParents]; 
xparcnts=parents; 

1 catch(*.J I 

Krror{"Could not allocate storage for"."parents*): 

cha r * cp=FileStore(); 
sficanf (ep. "%ld".£inumPeriods}; 
if (miniPeriodfl>HAXNIIMPERT0nS3 

Error( 

•The number of periods exceeds MAXNUMPERIODS = ", 
MAXNUHPERIODS. 

“\nFlease adjust MAXNUHPERIOBS in PT-compile* 
constants,h, and recompile**); 

I 

cp-l+EorwardTo(cp,kLlncRnd); 
for (long i=0;i<nuaiPare[Usii'^) 

I 

assert(*cp); 

cp-parentsUJ ,Init(cp,l); 

I 

qsort(parents,numParents.sizeof(Parent).Cmp<Parent>); 

) 

"SchedulesFileO (delete [] parents:! 
class ChildrenFile:public TextFile 
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// Rcjids thf rRhiklfcn file and w>rts chUda-n by tmne. 
i 

Child* children I 
public: 

Childt^nFiieflong tesiNuiiberXhttd* h xchildren, 
long& nufflChlldten} 

I 

Set F11 ennnetchil dr enFiJeKaiBe, test Number): 
uumCh11d r 0 n*H en d(chiId r enFileKame); 
try i 

chlldren=new Chi Id [niimChildcenl; 
xchildren“chlId ten: 

I catch(.*.) I 

Rrrori“Could not allocate storage for*'./'ch J Idren**): 

1 

char* cp’^Fi!eStereO; 

for {long IM): 1 <nujiiChlldren; i++) 

( 

assert{*cp); 

cp-children[il.Init(cp,i): 

qsort (ch I I d ren. n tiinChil dr en. sizeot (Chi Id). Cntp<Ch I Id > J: 

] 

^"ChildrenFileO fdelete [] children:! 


class TeachersFile:public TextFile 
// Reads the PRcachcfs fik. 

l 

Request* requests; 
public: 

TeacbersFlledong test Number. Request* & xrequests, 
longS numKequests) 

I 

SetFllenaiiie(teachersFileNaiiie.testNuiiiber) t 
ngmRoquests^Read (teachersFileNameJ: 
try t 

lequesLS'^riew Request: fnumRequests]; 

jnGDiset (requests.0. s 1 zcof (Request} *numRequeats); 

xrequests=requesta; 

) catch (...) [ 

Ertot(“Could not allocate storage for**."requests"); 

1 

char* cp"FlleStorB(); 

lor (long 1*0:l<numRequest£;i++) 

( 

assert(*cp3; 

cp^requestslij .Init tep.1): 

I 

qsort(requests.numRequest s.sizeo f(Request)* Caip<Reque3t>); 

1 

'-TeacbersFilflO Idelete [] requests:! 

class OutputFile:public TextFlle 
// Handkii Uic Pm-HMifcrcnccs iiuTpui file. 

I 

FILE* f; 
public: 

OutputFi ledong testNumber) :f(0) 

[ 

HetFllenaaiG(outpuTFi !eNaine.t€BtNuMber) : 

1 

void OpenO 
[ 

f-fopen{outputFileNairie."^*’}: 
assert(f): 

I 

void GloaoO 1 fclose(f);) 

void SendConference(Conferenced C) 

I 

assert(C.IsAssigned()}; 
fprintf(f.'*%s;%s.lUl\n% 

C.TheTeacher 0 ->Naaie() .C.TbeFareniO >NaBe{) .H. Period!3): 

) 

i: 

class LogFile 

// ElandJc^ Uw Fl-log fik. 

// lug c^icfHs m sitittd here, and oiripui logrthcr with a .single routine. 

i 

long nuralests; 
double* axecutlonTiroe: 
public: 


LogFIle(long n) : 
nuwTests(n). 

exec lit ioriTime (new d oub 1 e f 1 In ]) // tosis arc aambercd ( to n 

( 

meoset (executionTime* O.sl zeof (double) * (1+n)): 

1 

"[.ogFile t) (delete [) executionTime: 1 
void Set (long testNumber.double tlaie) 

I 

executionTl h»c I teatNumber 1 iae; 

) 

void Send() 
t 

FILE* f-fopen(log7ileNaine.'*w'*); 
assort(f): 

far (1 ong teKtHuMber=l: testNumber<^um*rests: testMumbor-H-) 

I 

fprinlf (f. "%i0.3f\ti“.executlonTliiielte£tNuflibGrJ): 

I 

fclose(f): 

I 

h 

ll^endlf 


MyTimer.h 

*ifndefMYTrMER3 
define MlrTlMiai^H 

/* tiasii: microsecond timer class. V 
“Inclutk <llincr.h> 

da.ss MyTimer 
{ 

UnsigncdWitlc startTime; 
publics 

My'FunerC)(RestartO; | 

void RestarlO IMiCKisccondstaatarfllme):) 
double Ela|>sc(lMitlibecsO const 
( 

UnsignedWidc cndTimc; 

MicmsecxintLsC^ciidTimc); 

return (CcndTime.lostartTlmc.lcj)/! 000.0): 

1 : 

*imdif 

PT-Compile- 

CONSTANTS.H 

lifndef PT_C0MP1LE_C0KSTANTSJT 
#<lefine fT_COMPILE_C0»STANTSJI 

r 

<'>ompik policies. 

Mostly self-explanatory. 

7 

^define DEG 0 

//!f profile_ 
j/imdef OBG 
#defrne OBO 0 
j^eridlf 


fif IDBG 
Idefine NDEBUG 
iendif 

^include (assert.h> 

#deflite xINLlNK_KEGlJRSmS 1 
^define IMPUT_D1 RECTORY rtlnputDaia;" 
Idefine HAXNUMPERIODE 255 
lend If 
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Tile below newi headlines recently crossed our news desk. For more information on 
each of these items, check out the MacTech web site <li Up://www. mac tech .com> and 
search out the below headlines from the home page. 


• Berkeley Releases 802.11b WLAN 
Security Monitoring Device 

• VINC vl,0 For Mac OS X and Ma(‘ 

OS 

• ChmnoSync Updated to Version L0.2 

• Xl^ay 1.0 - top Tret Info'^ utility for 
Mac OS X 

• NowPak Module Transfers Contacts 
to iPotl 

• Alann ClcKk F*r) 5.2 

• MeE^emill 1.5.3 with significant 
improvements 

• IntdliMci^c 2.1.5: Adding iPrxl 
Support 

• Karelia Sliips Watson 1.5 and 
Updated SDK 

• ABSpius 6(>GU now sliipping 

• StickyBrain is FREL. For two days 
only. 

• Terra Soli Ships Yellow Dog Linux 

2.2 

• Carbon Events plug-in for ItEAlJJasic, 
version 2.5 

• REAL Software announces diis yearns 
Cubies contest 

• ActiveX D 2.CM released 

• Troll Toucli announces TouchStar2 
touch screen system for LCD iMac 

• FileXaminer LObt Releaserl 

• Dantz Ships Rctrosfxrct Backup 5.0 
For Mac Os X 

• Imacination Software Announces 
Web Application Dcvelopmcnl 

• SQL4X Manager J released 

• Remote Control Aromik 3^0 

• Bare Bones Softwart: Releiises 
Mailsmith 1.5 for Mac OS X 

• MacHack 17: Keynote Announced: 
Tim O^Rdlly 

• Fwd: Press Infonnadori: SQL^iX 
Manager J released 

• TCP Server Deux vl .0.0 Released by 
Deep Sky Teclmologies 

• ASG Announces ZipCenter 1.6 
Update and Q2 2002 Data 

• Revolution t.l J Ix^ta 2 (RCl) for 
Windows, Mac and Linux 

■ STfMlJTTJS 2.0 


March 2002 • MacTech 


MACVCD X 4.0 RELEASED - Play VCDs 
on OS X 

Apple In Volume Prtxiuction of New 

iMacs, $K)0 IVice Increase 

Apple Intrtxluces 10GB iPod-2,000 

Songs in Your Pocket 

Apple Unveils Cinema HD 23'inch Flat 

Panel Disi>lay 

Apple Previews Bliieta^th Wireless 
Cxinnectiviry for Mac OS X 
IPNelMonitor for OS X 
Web Page Cilentlar Maker 1.0 
NetCloak 3.2 For OS X 
PrcfsOverload 4.1.1 For Mac OS And 
Mac Os X 

IntelliMerge 2.1 For Mac OS 

WT IniRxluces VvidgelfTMJ Prcxliid 

Name (Formerly called 

illumineX adds new modules to Screen 

Saver Pack 1. L2 For Mac OS X 

MactnMind Software updates Lite server 

account utility. Passenger 

HEMRIS Ships Ximctor 

WielK-Tech FireWire DriveDtKk 

Shipping 

RRAljdb Tools 1.2 now available 
New REALIxisic dauibasc and Microsoft 
Office Automation plug-ins 
RKALhasic 4.0.2 Now Available 
[Replace LI advanced find and replace 
for hunl 

Koingo Updates Alarm Clock Pro 
CPLAT 4.0 released 
Iconfactory Releases fconViewer 1.0 
Post.Office Is Alive And Well On Mac 
OS X 

Captain FTP L2 for Mac OS X 
Troi Grabber Plug-in 1.4bl for 
FileMaker Pro 5-5 
aegi dispatcher for Mac OS X 
MaesDesign Studio Releases Web Hcl]> 
Desk 5.4 

Tlie Omni Group Announces 
OinniOutliner 2.0 public lx.‘ta 
Chronos Group Organizer Server Now 
In Ccx'oa 

Niemeijcr Amrounccs On-Screen 
Keyboard Acce.ssibility for Mac OS X 
PC-Mac-Net FileShare transfers files 
easily lietween PCs and Mac’s 
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